/ Hex Artifact Content
Login

Artifact 3be4d9a7d38ef83fadd4aadd7ef3c6039e165da7:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 62  * Provide the ab
06b0: 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64  ility to overrid
06c0: 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 72  e linkage featur
06d0: 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66  es of the interf
06e0: 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ace..*/.#ifndef 
06f0: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20  SQLITE_EXTERN.# 
0700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
0710: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64  TERN extern.#end
0720: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0730: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53  E_API.# define S
0740: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66  QLITE_API.#endif
0750: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0760: 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 53  CDECL.# define S
0770: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64  QLITE_CDECL.#end
0780: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0790: 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 69  E_STDCALL.# defi
07a0: 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  ne SQLITE_STDCAL
07b0: 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  L.#endif../*.** 
07c0: 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72  These no-op macr
07d0: 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 66  os are used in f
07e0: 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63  ront of interfac
07f0: 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65  es to mark those
0800: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
0810: 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 61  s either depreca
0820: 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e  ted or experimen
0830: 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63  tal.  New applic
0840: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
0850: 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 61   not use depreca
0860: 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d  ted interfaces -
0870: 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f 72   they are suppor
0880: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
0890: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
08a0: 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  ty only.  Applic
08b0: 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68  ation writers sh
08c0: 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68  ould be aware th
08d0: 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74  at.** experiment
08e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
08f0: 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
0900: 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c  nge in point rel
0910: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eases..**.** The
0920: 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74  se macros used t
0930: 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72  o resolve to var
0940: 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f  ious kinds of co
0950: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61  mpiler magic tha
0960: 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72  t.** would gener
0970: 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73  ate warning mess
0980: 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77  ages when they w
0990: 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74  ere used.  But t
09a0: 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20  hat.** compiler 
09b0: 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67  magic ended up g
09c0: 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61  enerating such a
09d0: 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72   flurry of bug r
09e0: 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77  eports.** that w
09f0: 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20  e have taken it 
0a00: 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65  all out and gone
0a10: 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73   back to using s
0a20: 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61  imple.** noop ma
0a30: 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  cros..*/.#define
0a40: 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
0a50: 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  ED.#define SQLIT
0a60: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a  E_EXPERIMENTAL..
0a70: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65  /*.** Ensure the
0a80: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20  se symbols were 
0a90: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73  not defined by s
0aa0: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61  ome previous hea
0ab0: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66  der file..*/.#if
0ac0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0ad0: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ON.# undef SQLIT
0ae0: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66  E_VERSION.#endif
0af0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
0b00: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20  ERSION_NUMBER.# 
0b10: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  undef SQLITE_VER
0b20: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64  SION_NUMBER.#end
0b30: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
0b40: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
0b50: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
0b60: 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e   Numbers.**.** ^
0b70: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52  (The [SQLITE_VER
0b80: 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65  SION] C preproce
0b90: 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68  ssor macro in th
0ba0: 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64  e sqlite3.h head
0bb0: 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20  er.** evaluates 
0bc0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
0bd0: 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20  ral that is the 
0be0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69  SQLite version i
0bf0: 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20  n the.** format 
0c00: 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20  "X.Y.Z" where X 
0c10: 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72  is the major ver
0c20: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77  sion number (alw
0c30: 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c  ays 3 for.** SQL
0c40: 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74  ite3) and Y is t
0c50: 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e  he minor version
0c60: 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73   number and Z is
0c70: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d   the release num
0c80: 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20  ber.)^.** ^(The 
0c90: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
0ca0: 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f  NUMBER] C prepro
0cb0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73  cessor macro res
0cc0: 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65  olves to an inte
0cd0: 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ger.** with the 
0ce0: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30  value (X*1000000
0cf0: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77   + Y*1000 + Z) w
0d00: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a  here X, Y, and Z
0d10: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   are the same.**
0d20: 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e   numbers used in
0d30: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0d40: 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ].)^.** The SQLI
0d50: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0d60: 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20  R for any given 
0d70: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
0d80: 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62  e will also.** b
0d90: 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
0da0: 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77  e release from w
0db0: 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76  hich it is deriv
0dc0: 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69  ed.  Either Y wi
0dd0: 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f  ll.** be held co
0de0: 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c  nstant and Z wil
0df0: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64  l be incremented
0e00: 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20   or else Y will 
0e10: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a  be incremented.*
0e20: 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20  * and Z will be 
0e30: 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a  reset to zero..*
0e40: 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69  *.** Since versi
0e50: 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74  on 3.6.18, SQLit
0e60: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61  e source code ha
0e70: 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e  s been stored in
0e80: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
0e90: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73  "http://www.foss
0ea0: 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73  il-scm.org/">Fos
0eb0: 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  sil configuratio
0ec0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20  n management.** 
0ed0: 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68  system</a>.  ^Th
0ee0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ef0: 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74  ID macro evaluat
0f00: 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e  es to.** a strin
0f10: 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69  g which identifi
0f20: 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  es a particular 
0f30: 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69  check-in of SQLi
0f40: 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73  te.** within its
0f50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0f60: 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d  anagement system
0f70: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0f80: 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69  OURCE_ID.** stri
0f90: 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ng contains the 
0fa0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66  date and time of
0fb0: 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55   the check-in (U
0fc0: 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a  TC) and an SHA1.
0fd0: 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65  ** hash of the e
0fe0: 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65  ntire source tre
0ff0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1000: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1010: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1020: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1030: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
1040: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
1050: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
1060: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1070: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1080: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
1090: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
10a0: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
10b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
10c0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
10d0: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
10e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
10f0: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1100: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1110: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1120: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1130: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
1140: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1150: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
1160: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1170: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1180: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1190: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
11a0: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
11b0: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
11c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
11d0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
11e0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
11f0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1200: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
1210: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1220: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1230: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1240: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1250: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1260: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1270: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1280: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1290: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
12a0: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
12b0: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
12c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
12d0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
12e0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
12f0: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75  r, and thus insu
1300: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
1310: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
1320: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1330: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1340: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1350: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1360: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1370: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1380: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1390: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
13a0: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
13b0: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
13c0: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
13d0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
13e0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
13f0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
1400: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
1410: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
1420: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1430: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1440: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1450: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1460: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1470: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1480: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1490: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
14a0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
14b0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
14c0: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
14d0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
14e0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
14f0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1500: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
1510: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
1520: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1530: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1540: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1550: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1560: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1570: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1580: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1590: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
15a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
15b0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
15c0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
15d0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
15e0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
15f0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1600: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
1610: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
1620: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1630: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1640: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1650: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1660: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1670: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1680: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1690: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
16a0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
16b0: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
16c0: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
16d0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
16e0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
16f0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1700: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1710: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1720: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1730: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1740: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1750: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1760: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1770: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1780: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1790: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
17a0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
17b0: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
17c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
17d0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
17e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17f0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
1800: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
1810: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
1820: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1830: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1840: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1850: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1860: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1870: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1880: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
18b0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18c0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18d0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
18e0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
18f0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
1900: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
1910: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
1920: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1930: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1940: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1950: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1960: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1970: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1980: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1990: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
19a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
19b0: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
19c0: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
19d0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
19e0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
19f0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1a00: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a10: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1a20: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1a30: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1a40: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1a50: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1a60: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1a70: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1a80: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1a90: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1aa0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1ab0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ac0: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ad0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1ae0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1af0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1b00: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1b10: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1b20: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1b30: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1b40: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1b50: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1b60: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1b70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1b80: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1b90: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ba0: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1bb0: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1bc0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1bd0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1be0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1bf0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1c00: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1c10: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1c20: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1c30: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c40: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1c50: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c60: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1c70: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1c80: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1c90: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1ca0: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1cb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1cc0: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1cd0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1ce0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1cf0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1d00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1d10: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1d20: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1d30: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d40: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1d50: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1d60: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1d70: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1d80: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1d90: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1da0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1db0: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1dc0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1dd0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1de0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1df0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1e00: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1e10: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1e20: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1e30: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1e40: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1e50: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1e60: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1e70: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1e80: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1e90: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1ea0: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1eb0: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1ec0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1ed0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1ee0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1ef0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1f00: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1f10: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1f20: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1f30: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1f40: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1f50: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
1f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
1f70: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1f80: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1f90: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1fa0: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1fb0: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1fc0: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1fd0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1fe0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1ff0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
2000: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2010: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
2020: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2030: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2040: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2050: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2060: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2070: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2080: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2090: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
20a0: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
20b0: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
20c0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
20d0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
20e0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
20f0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
2100: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
2110: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
2120: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2130: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2150: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2160: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2170: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2180: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2190: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
21a0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
21b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
21c0: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
21d0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
21e0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
21f0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2200: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2210: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2220: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2230: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2240: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2250: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2260: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2270: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2280: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2290: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
22a0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
22b0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
22c0: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
22d0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
22e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
22f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2300: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2310: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2320: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2330: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2340: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2350: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2360: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2380: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2390: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
23a0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
23b0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
23c0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
23d0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
23e0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
23f0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2400: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2410: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2420: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2430: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2440: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2450: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2470: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2480: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2490: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
24a0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
24b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
24c0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
24d0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
24e0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
24f0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2500: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
2510: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2520: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2530: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2550: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2560: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2570: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2580: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2590: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
25a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
25b0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
25c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
25d0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
25e0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
25f0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2600: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
2610: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
2620: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2630: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2640: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2650: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2660: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2670: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2680: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2690: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
26a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
26b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
26c0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
26d0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
26e0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
26f0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2700: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2710: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
2720: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2730: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2740: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2750: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2760: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2770: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2780: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2790: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
27a0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
27b0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
27c0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
27d0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
27e0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
27f0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2800: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2810: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2820: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2830: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2840: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2850: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2870: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2880: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2890: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28a0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
28b0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
28c0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
28d0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
28e0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
28f0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
2900: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
2910: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2920: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2930: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2940: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
2950: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
2960: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
2970: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2980: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
2990: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
29a0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
29b0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
29c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
29d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
29e0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
29f0: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
2a00: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
2a10: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
2a20: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
2a30: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
2a40: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
2a50: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
2a60: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
2a70: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
2a80: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
2a90: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
2aa0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
2ab0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ac0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
2ad0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
2ae0: 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
2af0: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
2b00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2b10: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2b20: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
2b30: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
2b40: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
2b50: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2b60: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2b70: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2b80: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2b90: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
2ba0: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
2bb0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2bc0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
2bd0: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
2be0: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
2bf0: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
2c00: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
2c10: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2c20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2c30: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2c60: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
2c70: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2c80: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
2c90: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
2ca0: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
2cb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cc0: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
2cd0: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
2ce0: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
2cf0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
2d00: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
2d10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
2d20: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
2d30: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
2d40: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
2d50: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
2d60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
2d70: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
2d80: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
2d90: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
2da0: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
2db0: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
2dc0: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
2dd0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2de0: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
2df0: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
2e00: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
2e10: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
2e20: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
2e30: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
2e40: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
2e50: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
2e60: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
2e70: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
2e80: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
2e90: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
2ea0: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
2eb0: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
2ec0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2ed0: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2ee0: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2ef0: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2f00: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f10: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2f20: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2f30: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2f40: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
2f50: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
2f60: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
2f70: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
2f80: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
2f90: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2fa0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2fb0: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2fc0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2fd0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2fe0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2ff0: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
3000: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
3010: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
3020: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
3030: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
3040: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
3050: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
3060: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
3070: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
3080: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
3090: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
30a0: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
30b0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
30c0: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
30d0: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
30e0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30f0: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3100: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
3110: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3120: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
3130: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
3140: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
3150: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
3160: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
3170: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
3180: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
3190: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
31a0: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
31b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
31c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
31d0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
31e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
31f0: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
3200: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
3210: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
3220: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3230: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
3240: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3250: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
3260: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
3270: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
3280: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
3290: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
32a0: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
32b0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
32c0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
32d0: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
32e0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
32f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
3300: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
3310: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
3320: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e  se(sqlite3*);.in
3330: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  t sqlite3_close_
3340: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
3350: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
3360: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
3370: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
3380: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
3390: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
33a0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
33b0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
33c0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
33d0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
33e0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
33f0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
3400: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3410: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
3420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
3430: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
3440: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
3450: 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
3460: 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
3470: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
3480: 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e  terface is a con
3490: 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72  venience wrapper
34a0: 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
34b0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
34c0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
34d0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
34e0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a  3_finalize()],.*
34f0: 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e  * that allows an
3500: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
3510: 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61  run multiple sta
3520: 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a  tements of SQL.*
3530: 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  * without having
3540: 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66   to use a lot of
3550: 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20   C code. .**.** 
3560: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65  ^The sqlite3_exe
3570: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75  c() interface ru
3580: 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ns zero or more 
3590: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a  UTF-8 encoded,.*
35a0: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
35b0: 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  rate SQL stateme
35c0: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20  nts passed into 
35d0: 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
35e0: 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74  ,.** in the cont
35f0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
3600: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3610: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74   passed in as it
3620: 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  s 1st.** argumen
3630: 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  t.  ^If the call
3640: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66  back function of
3650: 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
3660: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3670: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
3680: 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69  LL, then it is i
3690: 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20  nvoked for each 
36a0: 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f  result row.** co
36b0: 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20  ming out of the 
36c0: 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74  evaluated SQL st
36d0: 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20  atements.  ^The 
36e0: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  4th argument to.
36f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3700: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
3710: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
3720: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
3730: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3740: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3750: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3760: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3770: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3780: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3790: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
37a0: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
37b0: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
37c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
37d0: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
37e0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
37f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3800: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
3810: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
3820: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
3830: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3840: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3850: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3860: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3870: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3880: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3890: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
38a0: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
38b0: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
38c0: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
38d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
38e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
38f0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
3900: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
3910: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
3920: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
3930: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3940: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3950: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3960: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3970: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3980: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3990: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
39a0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
39b0: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
39d0: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
39e0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
39f0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
3a00: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
3a10: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a20: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3a30: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3a40: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3a50: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3a60: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3a70: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3a80: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3a90: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3aa0: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3ab0: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3ac0: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3ad0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
3ae0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3af0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
3b00: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
3b10: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
3b20: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
3b30: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3b40: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3b50: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3b60: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3b70: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3b80: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3b90: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ba0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3bb0: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3bc0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3bd0: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
3be0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3bf0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c00: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
3c10: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
3c20: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
3c30: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3c40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3c50: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3c60: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3c70: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3c80: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3c90: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3ca0: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3cb0: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3cc0: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3cd0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3ce0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
3cf0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
3d00: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
3d10: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3d20: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3d30: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3d40: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3d50: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3d60: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3d70: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3d80: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3d90: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3da0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3db0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3dc0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3dd0: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3de0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3df0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
3e00: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
3e10: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
3e20: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
3e30: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3e40: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3e50: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3e60: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3e70: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3e80: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3e90: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3ea0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3eb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3ec0: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3ed0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
3ee0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3ef0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
3f00: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
3f10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3f20: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
3f30: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3f40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f50: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3f60: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3f70: 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64  not close the [d
3f80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f90: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3fa0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3fb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3fc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3fd0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3fe0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3ff0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4000: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
4010: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
4020: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
4030: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
4040: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4050: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
4060: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
4070: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
4080: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
4090: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
40a0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
40e0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
40f0: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4120: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4130: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4140: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4150: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4160: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4170: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
41b0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
41c0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
41f0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4200: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4210: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4220: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4230: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
4240: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4250: 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c  }.**.** Many SQL
4260: 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ite functions re
4270: 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20  turn an integer 
4280: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d  result code from
4290: 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a   the set shown.*
42a0: 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20  * here in order 
42b0: 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63  to indicate succ
42c0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a  ess or failure..
42d0: 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20  **.** New error 
42e0: 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64  codes may be add
42f0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
4300: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
4310: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
4320: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
4330: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4340: 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ns].*/.#define S
4350: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
4360: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
4370: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
4380: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
4390: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
43b0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
43c0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
43d0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
43e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43f0: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
4400: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
4410: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
4420: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
4430: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
4440: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
4450: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
4460: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4470: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
4480: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
4490: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
44a0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
44b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
44c0: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
44d0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
44e0: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
44f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4500: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
4510: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
4520: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
4530: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4540: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
4550: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
4560: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
4570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4580: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
4590: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
45a0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
45b0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
45c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
45d0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
45e0: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
45f0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
4600: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4620: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
4630: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
4640: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
4650: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
4660: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
4670: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
4680: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
4690: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
46a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46b0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
46c0: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
46d0: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
46e0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
46f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4700: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4710: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4720: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4730: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
4760: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
4770: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
4780: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4790: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
47a0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
47b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
47c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
47e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
47f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4800: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4810: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4820: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4830: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4840: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4850: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4860: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4870: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4880: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
48a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
48b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
48c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
48d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
48e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
48f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4900: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4910: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4920: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4930: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4940: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4960: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4970: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4980: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4990: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
49a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
49b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
49c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
49d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
49e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
49f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4a00: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4a10: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4a20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4a30: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4a40: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4a50: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4a60: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4a80: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4a90: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4aa0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4ab0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
4ad0: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
4ae0: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
4af0: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b10: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
4b20: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
4b30: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4b40: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4b50: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4b60: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4b70: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4b80: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4ba0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4bb0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4bc0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4bd0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4be0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4bf0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4c00: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4c10: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4c20: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4c30: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
4c40: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4c50: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
4c60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
4c70: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
4c80: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
4c90: 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 30 integer.** 
4ca0: 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20  [result codes]. 
4cb0: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
4cc0: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
4cd0: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
4ce0: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
4cf0: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
4d00: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
4d10: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
4d20: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
4d30: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
4d40: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
4d50: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
4d60: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
4d70: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
4d80: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
4d90: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
4da0: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
4db0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4dc0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4dd0: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4de0: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4df0: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4e00: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4e10: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4e20: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4e30: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4e40: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4e50: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4e60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4e70: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4e80: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4e90: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4ea0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4eb0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ec0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
4ed0: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
4ee0: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
4ef0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
4f00: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
4f10: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
4f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4f30: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
4f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
4f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f70: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
4f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f90: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
4fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
4fb0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
4fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fd0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
4fe0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
4ff0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5000: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5010: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5020: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5030: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5040: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5050: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
5070: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
50b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
5190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51a0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
51b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
51c0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
51d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51e0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
51f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5200: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5220: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5230: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5240: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5260: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
5270: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
5280: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
5290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52a0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
52b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52c0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
52d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52e0: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
52f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5300: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5320: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5330: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5340: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5360: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
5370: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5380: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
53b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53c0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
53d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53e0: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
53f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5400: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5420: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5430: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5440: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5460: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
5470: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5480: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
5490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54a0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
54b0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
54c0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
54f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5500: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5520: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5530: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5540: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5560: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
5570: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5580: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
5590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55a0: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
55b0: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
55c0: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
5610: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5620: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
5630: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5640: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5650: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5660: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
5670: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
5680: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5690: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
56b0: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
56c0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
56d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
56e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
56f0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
5700: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5710: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5720: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5730: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
5740: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5750: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5770: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5780: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5790: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
57b0: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
57c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
57d0: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
57e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
57f0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
5800: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5810: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
5820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5830: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
5840: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5850: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5860: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5870: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5880: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5890: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
58a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58b0: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
58d0: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5900: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5910: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5920: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5930: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5940: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5950: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5960: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5970: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5980: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5990: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59a0: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
59b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59c0: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
59d0: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
59e0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
59f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5a10: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5a20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a30: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5a40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a50: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5a60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a70: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a90: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5aa0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ab0: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ad0: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5ae0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5b00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5b20: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b40: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5ba0: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5bb0: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5bc0: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5be0: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5bf0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5c00: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5c10: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5c20: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5c30: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5c40: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5c60: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5c80: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5ca0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5cb0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5cc0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5cd0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ce0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5cf0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5d00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5d10: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5d20: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5d30: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5d40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d50: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5d60: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5d70: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5d80: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5d90: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5da0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5db0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5dc0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5dd0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5de0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5df0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5e00: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5e10: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5e20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5e30: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
5e40: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5e50: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5e60: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5e70: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5e80: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
5e90: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5ea0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
5eb0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
5ec0: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
5ed0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5ee0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
5ef0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
5f00: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
5f10: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5f20: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
5f30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5f40: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
5f50: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f60: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f70: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
5f80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5f90: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
5fa0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fb0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fc0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
5fd0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5fe0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
5ff0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6000: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6010: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6020: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
6030: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6040: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6050: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6060: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6070: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6080: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6090: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
60a0: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
60b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
60d0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
60e0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
60f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6100: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
6110: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
6120: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
6130: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6140: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6150: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6160: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6170: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6190: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
61a0: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
61b0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
61c0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
61d0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
61e0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
61f0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
6200: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6210: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6220: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
6230: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6240: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6250: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6260: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6270: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6280: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6290: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
62a0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
62b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
62d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
62e0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
62f0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
6300: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6310: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6320: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6330: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6340: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6350: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6360: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6370: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6380: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6390: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
63a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
63b0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
63c0: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
63d0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
63e0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
63f0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6400: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6410: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6420: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6430: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6440: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6450: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6460: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6470: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6480: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6490: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
64a0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
64b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
64c0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
64d0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
64e0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
64f0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6500: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6510: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6520: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6530: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6540: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6550: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6560: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6570: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6580: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6590: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
65a0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
65b0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
65c0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
65d0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
65e0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
65f0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6600: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6610: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6620: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6630: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6640: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6650: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6660: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6670: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6680: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6690: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
66a0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
66b0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
66c0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
66d0: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
66e0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
66f0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6700: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6710: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6720: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6730: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6740: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6750: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6760: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6770: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6780: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6790: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
67a0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
67b0: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
67c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
67d0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
67e0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
67f0: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6800: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6810: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6820: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6830: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6840: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6850: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6860: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6870: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6880: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6890: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
68a0: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
68b0: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
68c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68d0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
68e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6900: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6920: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6930: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6940: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6950: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6970: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6980: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6990: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
69a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69b0: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
69c0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
69d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69e0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
69f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a00: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6a10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a20: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6a30: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6a40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a50: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a70: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6a80: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6a90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6aa0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6ab0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6ac0: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6ad0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6af0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6b00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b10: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6b20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6b30: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6b40: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b60: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6b70: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6b80: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6b90: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6ba0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6bb0: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6bc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6bd0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6be0: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6bf0: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6c00: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c10: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6c20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6c30: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6c40: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6c50: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6c60: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6c70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6c80: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6c90: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6ca0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6cc0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6cd0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6ce0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6cf0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6d00: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6d10: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6d20: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6d30: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6d40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6d50: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6d60: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6d70: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6d80: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6d90: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6da0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6db0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6dc0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6dd0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6de0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6df0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6e00: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6e10: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6e20: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6e30: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6e40: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6e50: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6e60: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6e70: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6e80: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6e90: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6ea0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6eb0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6ec0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6ed0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6ee0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6ef0: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6f00: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6f10: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6f20: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6f30: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6f40: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6f50: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6f60: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6f70: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6f80: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6f90: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6fa0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6fb0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6fc0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6fd0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6fe0: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6ff0: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
7000: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
7010: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
7020: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
7030: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
7040: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
7050: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
7060: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
7070: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
7080: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7090: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
70a0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
70b0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70c0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
70d0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
70e0: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
70f0: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7100: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7110: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7120: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7130: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7140: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7150: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7160: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7170: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7180: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7190: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
71a0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
71b0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
71c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
71d0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
71e0: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
71f0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7200: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7210: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7220: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7230: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7240: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7250: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7260: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7270: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7290: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
72a0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
72b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
72c0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
72d0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
72e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
72f0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7300: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7310: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7320: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7330: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7340: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7350: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7360: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7370: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7380: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7390: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
73a0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
73b0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
73c0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
73d0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
73e0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
73f0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7400: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7410: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7420: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7430: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7440: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7450: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7460: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7470: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7480: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7490: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
74a0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
74b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
74c0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
74d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
74e0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
74f0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7500: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7510: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7520: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7530: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7540: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7550: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7560: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7570: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7580: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7590: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
75a0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
75b0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
75c0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
75d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
75e0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
75f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7600: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7610: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7620: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7630: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7640: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7650: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7660: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7670: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7680: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7690: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
76a0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
76b0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
76c0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
76d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
76e0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
76f0: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7700: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7710: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7720: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7730: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7740: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7750: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7760: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7770: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7780: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7790: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
77a0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
77b0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
77c0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
77d0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
77e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
77f0: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7810: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7820: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7830: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7840: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7850: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7860: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7870: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7880: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7890: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
78a0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
78b0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
78c0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
78d0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
78e0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
78f0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7900: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7910: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7920: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7930: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7940: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7950: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7960: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7970: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7980: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7990: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
79a0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
79b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
79c0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
79d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
79e0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
79f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a00: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7a10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a20: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7a30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7a40: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7a50: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7a60: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7a70: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7a80: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7a90: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7aa0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7ab0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7ac0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7ad0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7ae0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7af0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7b00: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7b10: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7b20: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7b30: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7b40: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7b50: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7b60: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7b70: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7b80: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7b90: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7ba0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7bb0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7bc0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7bd0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7be0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7bf0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7c00: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7c10: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7c20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7c30: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7c40: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7c50: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7c60: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7c70: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7c80: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7c90: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7ca0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7cb0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7cc0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7cd0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7ce0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7cf0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7d00: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7d10: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7d20: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7d30: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7d40: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7d50: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7d60: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7d70: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7d80: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7d90: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7da0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7db0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7dc0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7dd0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7de0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7df0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7e00: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7e10: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7e20: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7e30: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7e40: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
7e50: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
7e60: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7e70: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7e80: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7e90: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7ea0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7eb0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7ec0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7ed0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7ee0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7ef0: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7f00: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7f10: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7f20: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7f30: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7f40: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7f50: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7f60: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7f70: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7f80: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7f90: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7fa0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7fb0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7fc0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7fd0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7fe0: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7ff0: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
8000: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
8010: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
8020: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
8030: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
8040: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
8050: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
8060: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8070: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
8080: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8090: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
80a0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
80b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
80c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
80d0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
80e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80f0: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8100: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8110: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
8120: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8130: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
8140: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8150: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
8180: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8190: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
81c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81d0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
81e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8200: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8210: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8220: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8230: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8240: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8250: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8260: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8270: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
8280: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8290: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
82a0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
82b0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
82c0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
82d0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
82e0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
82f0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8300: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8310: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8320: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8330: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8340: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8350: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8360: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8370: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
8380: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8390: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
83a0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
83b0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
83c0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
83d0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
83e0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8400: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8410: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8420: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8430: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8440: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8450: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8460: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8470: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8480: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8490: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
84a0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
84b0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
84c0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
84d0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
84e0: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
84f0: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8500: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8510: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8520: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8530: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8540: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8550: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8560: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8570: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8590: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
85a0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
85b0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
85c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
85d0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
85e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
85f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8600: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8610: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8620: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8630: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8640: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8650: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8660: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8670: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8680: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8690: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
86a0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
86b0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
86c0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
86d0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
86e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
86f0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8700: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8710: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8720: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8730: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8740: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8750: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8760: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8770: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8780: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8790: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87a0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
87b0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
87c0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
87d0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
87e0: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
87f0: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8810: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8820: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8850: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8860: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8870: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8890: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
88a0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
88b0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
88c0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
88d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
88e0: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
88f0: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8900: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8910: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8920: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8930: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8940: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8950: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8960: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8970: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8980: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
89a0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
89b0: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
89c0: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
89d0: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
89e0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
89f0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8a00: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8a10: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8a20: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8a30: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8a40: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8a50: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8a60: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8a70: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8a80: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8a90: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8aa0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8ab0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8ac0: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8ad0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8ae0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8af0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8b00: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8b10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8b20: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8b30: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8b40: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8b50: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8b60: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8b70: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8b80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8b90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
8ba0: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
8bb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8bc0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8bd0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8be0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8bf0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8c00: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8c10: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8c20: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8c30: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8c40: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8c50: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8c60: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8c70: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8c80: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8c90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8ca0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8cb0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8cc0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8cd0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8ce0: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8cf0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8d00: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8d10: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8d20: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
8d30: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
8d40: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
8d50: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
8d60: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
8d70: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d80: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
8d90: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8da0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
8db0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
8dc0: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
8dd0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
8de0: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
8df0: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
8e00: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
8e10: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
8e20: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
8e30: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
8e40: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
8e50: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
8e60: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
8e70: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
8e80: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
8e90: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
8ea0: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
8eb0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8ec0: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
8ed0: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
8ee0: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
8ef0: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
8f00: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
8f10: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
8f20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8f30: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
8f40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8f50: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
8f60: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8f70: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
8f80: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
8f90: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
8fa0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8fb0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8fc0: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8fd0: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8fe0: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8ff0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9000: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9010: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9020: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9030: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
9040: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
9050: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
9060: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9070: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9080: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9090: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
90a0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
90b0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
90c0: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
90d0: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
90e0: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
90f0: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9100: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9110: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9130: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
9140: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9150: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
9160: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9170: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9180: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9190: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
91a0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
91b0: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
91c0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
91d0: 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20  ction.  See the 
91e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
91f0: 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e  ntrol()] documen
9200: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64  tation for.** ad
9210: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
9220: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
9230: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9240: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9250: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9260: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9280: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9290: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
92a0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
92b0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
92c0: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
92d0: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
92e0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
92f0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
9300: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
9310: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
9320: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
9330: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9340: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9350: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9360: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9370: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9380: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9390: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
93a0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
93b0: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
93c0: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
93d0: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
93e0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
93f0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9400: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9410: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9420: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9430: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9440: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9450: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9460: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9470: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9480: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9490: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
94a0: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
94b0: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
94c0: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
94d0: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
94e0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
94f0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9500: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9510: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9520: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9530: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9540: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9550: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9560: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9570: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9580: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9590: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
95a0: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
95b0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
95c0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
95d0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
95e0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
95f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9600: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9610: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9620: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9630: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9640: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9650: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9660: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9670: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9680: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9690: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
96a0: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
96b0: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
96c0: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
96d0: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
96e0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
96f0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9700: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9710: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9720: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9730: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9740: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9750: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9760: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9770: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9780: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9790: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
97a0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
97b0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
97c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
97d0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
97e0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
97f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9800: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9810: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9820: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9830: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9840: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9850: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9860: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9870: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9880: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9890: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
98a0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
98b0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
98c0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
98d0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
98e0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
98f0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9900: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9910: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9920: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9930: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
9940: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
9950: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
9960: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
9970: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
9980: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
9990: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
99a0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
99b0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
99c0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
99d0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
99e0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
99f0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9a00: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9a10: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9a20: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9a30: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9a40: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9a50: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9a60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9a70: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
9a80: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9a90: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9aa0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9ab0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9ac0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9ad0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9ae0: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9af0: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9b00: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9b10: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9b20: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9b30: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9b40: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9b50: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9b60: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
9b70: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
9b80: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9b90: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9ba0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9bb0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9bc0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9bd0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9be0: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9bf0: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9c00: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9c10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c20: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9c30: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9c40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9c50: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9c60: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9c70: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9c80: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9c90: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9ca0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9cb0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9cc0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9cd0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9ce0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9cf0: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9d00: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9d10: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9d20: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9d30: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9d40: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9d50: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9d60: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
9d70: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
9d80: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9d90: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9da0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
9db0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
9dc0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9dd0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9de0: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9df0: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9e00: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9e10: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9e20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9e30: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
9e40: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
9e50: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
9e60: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9e70: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
9e80: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
9e90: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
9ea0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
9eb0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
9ec0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9ed0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9ee0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9ef0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9f00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9f10: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9f20: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9f30: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
9f40: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
9f50: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
9f60: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
9f70: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
9f80: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9f90: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9fa0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9fb0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
9fc0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9fd0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9fe0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9ff0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
a000: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a010: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a020: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a030: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a040: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a050: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
a060: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
a070: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
a080: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
a090: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
a0a0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
a0b0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
a0c0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
a0d0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
a0e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
a0f0: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
a100: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a110: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a120: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a130: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a140: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a150: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a160: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a170: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
a180: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a190: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
a1a0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
a1b0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a1c0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a1d0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a1e0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a1f0: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
a200: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
a210: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a220: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a230: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a250: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a260: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a270: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
a280: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
a290: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
a2a0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
a2b0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
a2c0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
a2d0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
a2e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a2f0: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
a300: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
a310: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
a320: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
a330: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
a340: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
a350: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a360: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
a370: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a380: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
a390: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
a3a0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
a3b0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
a3c0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
a3d0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
a3e0: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
a3f0: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
a400: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
a410: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
a420: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
a430: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
a440: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
a450: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
a460: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
a470: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
a480: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
a490: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a4b0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
a4c0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
a4d0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
a4e0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
a4f0: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
a500: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
a510: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
a520: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
a530: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
a540: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
a550: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
a560: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
a570: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
a580: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
a590: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
a5a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
a5b0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
a5c0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
a5d0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
a5e0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
a5f0: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
a600: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
a610: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
a620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a630: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
a640: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
a650: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
a660: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
a670: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
a680: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
a690: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
a6a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
a6b0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
a6c0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
a6d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
a6e0: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
a6f0: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
a700: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
a710: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
a720: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a730: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a740: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
a750: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
a760: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
a770: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
a780: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
a790: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
a7a0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
a7b0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
a7c0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
a7d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
a7e0: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
a7f0: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
a800: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
a810: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
a820: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
a830: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a840: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
a850: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
a860: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
a870: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
a880: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
a890: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
a8a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
a8b0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
a8c0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
a8d0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
a8e0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
a8f0: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
a900: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
a910: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
a920: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
a930: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
a940: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a950: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a960: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
a970: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
a980: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
a990: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
a9a0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
a9b0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
a9c0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
a9d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a9e0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a9f0: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
aa00: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
aa10: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
aa20: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
aa30: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
aa40: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
aa50: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
aa60: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
aa70: 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  if result string
aa80: 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61   is NULL, or tha
aa90: 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  t returns a copy
aaa0: 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
aab0: 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20  t string if the 
aac0: 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55  string is non-NU
aad0: 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  LL..** ^If the [
aae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aaf0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ab00: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
ab10: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
ab20: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
ab30: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
ab40: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
ab50: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
ab60: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
ab70: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
ab80: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
ab90: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
aba0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
abb0: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
abc0: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
abd0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
abe0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
abf0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
ac00: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
ac10: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
ac20: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
ac30: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
ac40: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
ac50: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
ac60: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
ac70: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ac80: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ac90: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
aca0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
acb0: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
acc0: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
acd0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
ace0: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
acf0: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
ad00: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
ad10: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
ad20: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
ad30: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
ad40: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
ad50: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
ad60: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
ad70: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
ad80: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
ad90: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
ada0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
adb0: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
adc0: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
add0: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
ade0: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
adf0: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
ae00: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
ae10: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
ae20: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ae30: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
ae40: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
ae50: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
ae60: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
ae70: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
ae80: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
ae90: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
aea0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
aeb0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
aec0: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
aed0: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
aee0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aef0: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
af00: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
af10: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
af20: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
af30: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
af40: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
af50: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
af60: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
af70: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
af80: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
af90: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
afa0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
afb0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
afc0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
afd0: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
afe0: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
aff0: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
b000: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
b010: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
b020: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
b030: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
b040: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
b050: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
b060: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
b070: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
b080: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
b090: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
b0a0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
b0b0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
b0c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
b0d0: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
b0e0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
b0f0: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
b100: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
b110: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
b120: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b130: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b140: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b150: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b160: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
b170: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
b180: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
b190: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b1a0: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
b1b0: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
b1c0: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
b1d0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
b1e0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
b1f0: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
b200: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
b210: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
b220: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
b230: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
b240: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
b250: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
b260: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
b270: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
b280: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
b290: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
b2a0: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
b2b0: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
b2c0: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
b2d0: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
b2e0: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
b2f0: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
b300: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
b310: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
b320: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
b330: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
b340: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
b350: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
b360: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
b370: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
b380: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b390: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
b3a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b3b0: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
b3c0: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
b3d0: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
b3e0: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
b3f0: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
b400: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
b410: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
b420: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
b430: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
b440: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
b450: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
b460: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
b470: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b480: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
b490: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
b4a0: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
b4b0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
b4c0: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
b4d0: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
b4e0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b4f0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
b500: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
b510: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
b520: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
b530: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b540: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
b550: 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20  _MOVED]].** The 
b560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b570: 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f  S_MOVED] file co
b580: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
b590: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
b5a0: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
b5b0: 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
b5c0: 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c  it writes a bool
b5d0: 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  ean into that in
b5e0: 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a  teger depending.
b5f0: 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72  ** on whether or
b600: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61   not the file ha
b610: 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20  s been renamed, 
b620: 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65  moved, or delete
b630: 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61  d since it.** wa
b640: 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a  s first opened..
b650: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b660: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b670: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
b680: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b690: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b6a0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
b6b0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
b6c0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
b6d0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
b6e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
b6f0: 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65  to swap the file
b700: 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65   handle with the
b710: 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20   one.** pointed 
b720: 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61  to by the pArg a
b730: 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63  rgument.  This c
b740: 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65  apability is use
b750: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
b760: 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  .** and only nee
b770: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
b780: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
b790: 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  EST is defined..
b7a0: 2a 2a 0a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  **.* <li>[[SQLIT
b7b0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
b7c0: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
b7d0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
b7e0: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
b7f0: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
b800: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
b810: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
b820: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
b830: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
b840: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
b850: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
b860: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
b870: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
b880: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
b890: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
b8a0: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
b8b0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
b8c0: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
b8d0: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
b8e0: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
b8f0: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
b900: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
b910: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
b920: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b930: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
b940: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b950: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
b960: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
b970: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
b980: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
b990: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
b9a0: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
b9b0: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
b9c0: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  e..** </ul>.*/.#
b9d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b9e0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
b9f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
ba00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba10: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
ba20: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
ba30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba40: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
ba50: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
ba60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ba70: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
ba80: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
ba90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
baa0: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
bab0: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
bac0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
bad0: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
bae0: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
baf0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
bb00: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
bb10: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
bb20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
bb30: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
bb40: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
bb50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bb60: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
bb70: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
bb80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
bb90: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
bba0: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
bbc0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
bbd0: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
bbe0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
bbf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bc00: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
bc10: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
bc20: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
bc30: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
bc40: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
bc50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
bc60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc70: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
bc80: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
bc90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bca0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
bcb0: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
bcc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bcd0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
bce0: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
bcf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd00: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
bd10: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
bd20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd30: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
bd40: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
bd50: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd60: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
bd70: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
bd80: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bd90: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
bda0: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
bdb0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
bdc0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
bdd0: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
bde0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
bdf0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
be00: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
be10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
be20: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
be30: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
be40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 54 41 20  QLITE_FCNTL_OTA 
be50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
be60: 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65 63     26../* deprec
be70: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
be80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
be90: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
bea0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
beb0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
bec0: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
bed0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
bee0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
bef0: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
bf00: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
bf10: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
bf20: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
bf30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
bf40: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
bf50: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
bf60: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
bf70: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
bf80: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
bf90: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
bfa0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
bfb0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
bfc0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
bfd0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
bfe0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
bff0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
c000: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
c010: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
c020: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
c030: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
c040: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
c050: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
c060: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
c070: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
c080: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
c090: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
c0a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c0b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
c0c0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
c0d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
c0e0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
c0f0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
c100: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
c110: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
c120: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
c130: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
c140: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
c150: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
c160: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
c170: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
c180: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
c190: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
c1a0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
c1b0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
c1c0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
c1d0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
c1e0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
c1f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
c200: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
c210: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
c220: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
c230: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
c240: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
c250: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
c260: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
c270: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
c280: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
c290: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
c2a0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
c2b0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
c2c0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
c2d0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
c2e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c2f0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
c300: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
c310: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
c320: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
c330: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
c340: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
c350: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
c360: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
c370: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
c380: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
c390: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
c3a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
c3b0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
c3c0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
c3d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
c3e0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
c3f0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
c400: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
c410: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
c420: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
c430: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
c440: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
c450: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
c460: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
c470: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c480: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
c490: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
c4a0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
c4b0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
c4c0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
c4d0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
c4e0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
c4f0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
c500: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
c510: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
c520: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
c530: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
c540: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
c550: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
c560: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
c570: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
c580: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
c590: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
c5a0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
c5b0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
c5c0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
c5d0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
c5e0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
c5f0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
c600: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c610: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c620: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c630: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c640: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c650: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c660: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c670: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c680: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c690: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c6a0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c6b0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c6c0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c6d0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c6e0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c6f0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c700: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c710: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c720: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c730: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c740: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c750: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c760: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c770: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c780: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c790: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c7a0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c7b0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c7c0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c7d0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
c7e0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
c7f0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
c800: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
c810: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
c820: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
c830: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
c840: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
c850: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
c860: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
c870: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
c880: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
c890: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
c8a0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
c8b0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
c8c0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
c8d0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
c8e0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
c8f0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
c900: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
c910: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
c920: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
c930: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
c940: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
c950: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
c960: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
c970: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
c980: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
c990: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c9a0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
c9b0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
c9c0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
c9d0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
c9e0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
c9f0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
ca00: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
ca10: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
ca20: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
ca30: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
ca40: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
ca50: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
ca60: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
ca70: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
ca80: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
ca90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
caa0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
cab0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
cac0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
cad0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
cae0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
caf0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
cb00: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
cb10: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
cb20: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
cb30: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
cb40: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
cb50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
cb60: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
cb70: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
cb80: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
cb90: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
cba0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
cbb0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
cbc0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
cbd0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
cbe0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
cbf0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
cc00: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
cc10: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
cc20: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
cc30: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
cc40: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
cc50: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
cc60: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
cc70: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
cc80: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
cc90: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cca0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
ccb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
ccc0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
ccd0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cce0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
ccf0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cd00: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
cd10: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cd20: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
cd30: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
cd40: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
cd50: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
cd60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
cd70: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
cd80: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cd90: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
cda0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
cdb0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
cdc0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
cdd0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
cde0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
cdf0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
ce00: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
ce10: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
ce20: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
ce30: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
ce40: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
ce50: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
ce60: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
ce70: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
ce80: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
ce90: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
cea0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
ceb0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
cec0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
ced0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
cee0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
cef0: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
cf00: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
cf10: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
cf20: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
cf30: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
cf40: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
cf50: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
cf60: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
cf70: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
cf80: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
cf90: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
cfa0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
cfb0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
cfc0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
cfd0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
cfe0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
cff0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d000: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d010: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d020: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d030: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d040: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d050: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d060: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d070: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d080: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d090: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d0a0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d0b0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
d0c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d0d0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d0e0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
d0f0: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
d100: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
d110: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
d120: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
d130: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
d140: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
d150: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
d160: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
d170: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
d180: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
d190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d1a0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
d1b0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
d1c0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
d1d0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
d1e0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
d1f0: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
d200: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
d210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d220: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
d230: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
d240: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
d250: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
d260: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
d270: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
d280: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
d290: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
d2a0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
d2b0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
d2c0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
d2d0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
d2e0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
d2f0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
d300: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
d310: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
d320: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
d330: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
d340: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
d350: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
d360: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
d370: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
d380: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
d390: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
d3a0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
d3b0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d3c0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
d3d0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
d3e0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
d3f0: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
d400: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
d410: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
d420: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
d430: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d440: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
d450: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
d460: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
d470: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
d480: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
d490: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
d4a0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
d4b0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
d4c0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
d4d0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d4e0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
d4f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
d500: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
d510: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
d520: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
d530: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
d540: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
d550: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d560: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
d570: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d580: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
d590: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
d5a0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
d5b0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
d5c0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
d5d0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d5e0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
d5f0: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
d600: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d610: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d620: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d630: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d640: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d650: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d660: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d670: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d680: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d690: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d6a0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d6b0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d6c0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d6d0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d6e0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d6f0: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d700: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d710: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d720: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d730: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d740: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d750: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d760: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d770: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d780: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d790: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d7a0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d7b0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d7c0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d7d0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
d7e0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
d7f0: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
d800: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
d810: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
d820: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
d830: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
d840: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
d850: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
d860: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
d870: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
d880: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
d890: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
d8a0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
d8b0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
d8c0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
d8d0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
d8e0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
d8f0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
d900: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
d910: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
d920: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
d930: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
d940: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
d950: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
d960: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
d970: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
d980: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
d990: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d9a0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
d9b0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
d9c0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
d9d0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
d9e0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
d9f0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
da00: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
da10: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
da20: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
da30: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
da40: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
da50: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
da60: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
da70: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
da80: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
da90: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
daa0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
dab0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
dac0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
dad0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
dae0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
daf0: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
db00: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
db10: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
db20: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
db30: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
db40: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
db50: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
db60: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
db70: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
db80: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
db90: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
dba0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
dbb0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
dbc0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
dbd0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
dbe0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
dbf0: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
dc00: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
dc10: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
dc20: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
dc30: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
dc40: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
dc50: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
dc60: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
dc70: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
dc80: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
dc90: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
dca0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
dcb0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
dcc0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
dcd0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
dce0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
dcf0: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
dd00: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
dd10: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
dd20: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
dd30: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
dd40: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
dd50: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
dd60: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
dd70: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
dd80: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
dd90: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
dda0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
ddb0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
ddc0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
ddd0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
dde0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
ddf0: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
de00: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
de10: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
de20: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
de30: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
de40: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
de50: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
de60: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
de70: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
de80: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
de90: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
dea0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
deb0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
dec0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
ded0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
dee0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
def0: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
df00: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
df10: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
df20: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
df30: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
df40: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
df50: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
df60: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
df70: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
df80: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
df90: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
dfa0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
dfb0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
dfc0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
dfd0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
dfe0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
dff0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e000: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e010: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e020: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e030: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e040: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e050: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e060: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e070: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e080: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e090: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e0a0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e0b0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
e0c0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
e0d0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
e0e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
e0f0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
e100: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
e110: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
e120: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
e130: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
e140: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
e150: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
e160: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
e170: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e180: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e190: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
e1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
e1b0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
e1c0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
e1d0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
e1e0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e1f0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e200: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
e210: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
e220: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e230: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e240: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
e250: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
e260: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
e270: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e280: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e290: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
e2a0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
e2b0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
e2c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e2d0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
e2e0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
e2f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e300: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
e310: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
e320: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
e330: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
e340: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
e350: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
e360: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
e370: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
e380: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
e390: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
e3a0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
e3b0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
e3c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
e3d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e3e0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
e3f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
e400: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
e410: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
e420: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
e430: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
e440: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
e450: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e460: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e470: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
e480: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e490: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
e4a0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
e4b0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
e4c0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
e4d0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
e4e0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
e4f0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
e500: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
e510: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
e520: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e530: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e540: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
e550: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e560: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e570: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
e580: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
e590: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
e5a0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
e5b0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e5c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e5d0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
e5e0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
e5f0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e600: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e610: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e620: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e630: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e640: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e650: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e660: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e670: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e680: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e690: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e6a0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e6b0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e6c0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e6d0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e6e0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e6f0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e700: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e710: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e720: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e730: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e740: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e750: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e760: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e770: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e780: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e790: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e7a0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e7b0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e7c0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e7d0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
e7e0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e7f0: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
e800: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
e810: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
e820: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e830: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
e840: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e850: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
e860: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e870: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
e880: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e890: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
e8a0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e8b0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
e8c0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e8d0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e8e0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
e8f0: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
e900: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
e910: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
e920: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
e930: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
e940: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
e950: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
e960: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
e970: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e980: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
e990: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
e9a0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
e9b0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
e9c0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
e9d0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
e9e0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
e9f0: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
ea00: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
ea10: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ea20: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
ea30: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
ea40: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
ea50: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
ea60: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
ea70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
ea80: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
ea90: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
eaa0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
eab0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
eac0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
ead0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
eae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
eaf0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
eb00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
eb10: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
eb20: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
eb30: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
eb40: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
eb50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
eb60: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
eb70: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
eb80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
eb90: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
eba0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
ebb0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
ebc0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
ebd0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
ebe0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
ebf0: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
ec00: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
ec10: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
ec20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
ec30: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
ec40: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
ec50: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
ec60: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
ec70: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
ec80: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
ec90: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
eca0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
ecb0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
ecc0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ecd0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
ece0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
ecf0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ed00: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ed10: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
ed20: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
ed30: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
ed40: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
ed50: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
ed60: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
ed70: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
ed80: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
ed90: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
eda0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
edb0: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
edc0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
edd0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
ede0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
edf0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
ee00: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
ee10: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
ee20: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
ee30: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
ee40: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
ee50: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
ee60: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
ee70: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
ee80: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
ee90: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
eea0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
eeb0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
eec0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
eed0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
eee0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
eef0: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
ef00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
ef10: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
ef20: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
ef30: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
ef40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
ef50: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
ef60: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
ef70: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
ef80: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
ef90: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
efa0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
efb0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
efc0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
efd0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
efe0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
eff0: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f010: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f020: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f030: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f040: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f050: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f060: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f070: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f080: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f090: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f0a0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f0b0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
f0c0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
f0d0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
f0e0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
f0f0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f100: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
f110: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
f120: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
f130: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
f140: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
f150: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
f160: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
f170: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
f180: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
f190: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
f1a0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
f1b0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
f1c0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
f1d0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f1e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f1f0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
f200: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
f210: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
f220: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
f230: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
f240: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
f250: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
f260: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
f270: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f280: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
f290: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f2a0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
f2b0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
f2c0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f2d0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
f2e0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
f2f0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
f300: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
f310: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
f320: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
f330: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
f340: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
f350: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
f360: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f370: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f380: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
f390: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
f3a0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f3b0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
f3c0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
f3d0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
f3e0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
f3f0: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
f400: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f410: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
f420: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
f430: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
f440: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
f450: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
f460: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f470: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f480: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f490: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
f4a0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
f4b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f4c0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
f4d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f4e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
f4f0: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
f500: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
f510: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
f520: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
f530: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
f540: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
f550: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
f560: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
f570: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
f580: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
f590: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
f5a0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
f5b0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
f5c0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
f5d0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
f5e0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f5f0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
f600: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f610: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f620: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f630: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f640: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f650: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f660: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f670: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f680: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f690: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f6a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f6b0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f6c0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f6d0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f6e0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f6f0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f700: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f710: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f720: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f730: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f740: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f750: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f760: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f770: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f780: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f790: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f7a0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f7b0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f7c0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f7d0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
f7e0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
f7f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f800: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
f810: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
f820: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
f830: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
f840: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
f850: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
f860: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
f870: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
f880: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
f890: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
f8a0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
f8b0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
f8c0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
f8d0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
f8e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f8f0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f900: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
f910: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f920: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
f930: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
f940: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f950: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
f960: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
f970: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
f980: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
f990: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f9a0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
f9b0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f9c0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f9d0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
f9e0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
f9f0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
fa00: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
fa10: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
fa20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa30: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
fa40: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
fa50: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
fa60: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
fa70: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
fa80: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
fa90: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
faa0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
fab0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
fac0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
fad0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fae0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
faf0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
fb00: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
fb10: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
fb20: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
fb30: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
fb40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fb50: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
fb60: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
fb70: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
fb80: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
fb90: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
fba0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
fbb0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
fbc0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
fbd0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
fbe0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
fbf0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
fc00: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
fc10: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
fc20: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
fc30: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
fc40: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
fc50: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
fc60: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
fc70: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
fc80: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
fc90: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
fca0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
fcb0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
fcc0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
fcd0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
fce0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
fcf0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
fd00: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
fd10: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
fd20: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
fd30: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
fd40: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
fd50: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
fd60: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
fd70: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
fd80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fd90: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
fda0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
fdb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fdc0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
fdd0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
fde0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
fdf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fe00: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
fe10: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
fe20: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
fe30: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
fe40: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
fe50: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
fe60: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
fe70: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
fe80: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
fe90: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
fea0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
feb0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
fec0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
fed0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
fee0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
fef0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
ff00: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
ff10: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
ff20: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
ff30: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
ff40: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
ff50: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
ff60: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ff70: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
ff80: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
ff90: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
ffa0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
ffb0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
ffc0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
ffd0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
ffe0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
fff0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
10000 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
10010 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
10020 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
10030 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
10040 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
10050 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10060 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
10070 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
10080 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
10090 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
100a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
100b0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
100c0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
100d0 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
100e0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
100f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10100 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10110 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
10120 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
10130 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10140 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
10150 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
10160 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
10170 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
10180 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
10190 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
101a0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
101b0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
101c0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
101d0 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
101e0 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
101f0 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
10200 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
10210 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
10220 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
10230 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
10240 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10250 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10260 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
10270 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
10280 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
10290 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
102a0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
102b0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
102c0 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
102d0 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
102e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
102f0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
10300 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
10310 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
10320 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
10330 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
10340 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
10350 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
10360 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10370 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
10380 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
10390 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
103a0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
103b0 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
103c0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
103d0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
103e0 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
103f0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10400 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
10410 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
10420 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
10430 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
10440 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
10450 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
10460 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
10470 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
10480 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10490 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
104a0 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
104b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
104c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
104d0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
104e0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
104f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
10500 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
10510 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
10520 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
10530 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
10540 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10550 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
10560 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
10570 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10580 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
10590 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
105a0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
105b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
105c0 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
105d0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
105e0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
105f0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
10600 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10610 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10620 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10630 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10640 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10650 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
10660 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
10670 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
10680 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
10690 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
106a0 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
106b0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
106c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
106d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
106e0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
106f0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10700 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
10710 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10720 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
10730 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
10740 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
10750 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
10760 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
10770 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
10780 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
10790 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
107a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
107b0 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
107c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
107d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
107e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
107f0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10800 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
10810 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
10820 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10830 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
10840 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
10850 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
10860 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
10870 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
10880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10890 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
108a0 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
108b0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
108c0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
108d0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
108e0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
108f0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
10900 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
10910 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
10920 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
10930 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
10940 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
10950 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
10960 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
10970 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
10980 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10990 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
109a0 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
109b0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
109c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
109d0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
109e0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
109f0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
10a00 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
10a10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10a20 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
10a30 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
10a40 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
10a50 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
10a60 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
10a70 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
10a80 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10a90 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
10aa0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
10ab0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10ac0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
10ad0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
10ae0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
10af0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
10b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10b10 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10b20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
10b30 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10b40 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
10b50 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
10b60 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
10b70 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10b80 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
10b90 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
10ba0 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
10bb0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
10bc0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
10bd0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
10be0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
10bf0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
10c00 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
10c10 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10c20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10c30 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10c40 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10c50 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10c60 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
10c70 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
10c80 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
10c90 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
10ca0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10cb0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
10cc0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
10cd0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
10ce0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
10cf0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
10d00 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
10d10 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10d20 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10d30 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10d40 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10d50 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10d60 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10d70 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
10d80 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10d90 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
10da0 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
10db0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
10dc0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
10dd0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
10de0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
10df0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
10e00 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
10e10 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10e20 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10e30 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10e40 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10e50 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10e60 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
10e70 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
10e80 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
10e90 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10ea0 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
10eb0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
10ec0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
10ed0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
10ee0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
10ef0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10f00 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
10f10 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10f20 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10f30 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10f40 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
10f50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10f60 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
10f70 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
10f80 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
10f90 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
10fa0 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
10fb0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
10fc0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
10fd0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
10fe0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
10ff0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
11000 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
11010 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
11020 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
11030 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
11040 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
11050 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
11060 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
11070 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
11080 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
11090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110a0 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
110b0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
110c0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
110d0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
110e0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
110f0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
11100 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
11110 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
11120 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
11130 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
11140 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11150 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
11160 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
11170 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
11180 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
11190 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
111a0 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
111b0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
111c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
111d0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
111e0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
111f0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
11200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11210 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
11220 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
11230 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
11240 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
11250 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
11260 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
11270 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
11280 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
11290 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
112a0 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
112b0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
112c0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
112d0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
112e0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
112f0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
11300 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
11310 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
11320 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
11330 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
11340 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
11350 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
11360 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11370 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
11380 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
11390 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
113a0 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
113b0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
113c0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
113d0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
113e0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
113f0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
11400 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11410 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
11420 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
11430 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
11440 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
11450 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
11460 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
11470 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11480 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
11490 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
114a0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
114b0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
114c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
114d0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
114e0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
114f0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
11500 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
11510 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
11520 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
11530 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
11540 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11550 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11560 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11570 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11580 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11590 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
115a0 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
115b0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
115c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
115d0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
115e0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
115f0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
11600 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
11610 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
11620 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
11630 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
11640 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11650 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
11660 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
11670 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11680 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
11690 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
116a0 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
116b0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
116c0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
116d0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
116e0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
116f0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
11700 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
11710 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
11720 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
11730 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11740 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
11750 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11760 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
11770 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
11780 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11790 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
117a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
117b0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
117c0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
117d0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
117e0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
117f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
11800 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11810 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11820 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
11830 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
11840 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
11850 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11860 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11870 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
11880 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
11890 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
118a0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
118b0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
118c0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
118d0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
118e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
118f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11900 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
11910 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
11920 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
11930 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
11940 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
11950 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
11960 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11970 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
11980 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11990 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
119a0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
119b0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
119c0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
119d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
119e0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
119f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11a00 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
11a10 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11a20 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
11a30 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
11a40 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
11a50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11a60 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11a70 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11a80 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
11a90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11aa0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
11ab0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
11ac0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
11ad0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
11ae0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
11af0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
11b00 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
11b10 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11b20 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
11b30 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11b40 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11b50 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11b60 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11b70 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11b80 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11b90 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11ba0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11bb0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11bc0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
11bd0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11be0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11bf0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
11c00 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
11c10 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
11c20 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
11c30 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
11c40 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
11c50 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11c60 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11c70 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11c80 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11c90 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11ca0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11cb0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11cc0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
11cd0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
11ce0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
11cf0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
11d00 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
11d10 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
11d20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11d30 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
11d40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11d50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11d70 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
11d80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11d90 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11da0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11db0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
11dc0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11dd0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
11de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11df0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11e00 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11e10 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11e20 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11e30 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
11e40 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
11e50 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11e60 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
11e70 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
11e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11e90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11ea0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11eb0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11ec0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
11ed0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
11ee0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
11ef0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11f00 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
11f10 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
11f20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
11f30 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
11f40 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
11f50 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
11f60 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
11f70 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
11f80 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
11f90 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
11fa0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
11fb0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
11fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11fd0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
11fe0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
11ff0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12000 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12010 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12020 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12030 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12040 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
12050 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12060 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
12070 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
12080 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12090 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
120a0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
120b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
120c0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
120d0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
120e0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
120f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12100 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
12110 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12120 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
12130 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12140 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
12150 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12160 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12170 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12180 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12190 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
121a0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
121b0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
121c0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
121d0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
121e0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
121f0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
12200 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
12210 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12220 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
12230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12240 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
12250 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
12260 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
12270 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
12280 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
12290 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
122a0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
122b0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
122c0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
122d0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
122e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
122f0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
12300 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
12310 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
12320 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
12330 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
12340 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12350 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
12360 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
12370 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
12380 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
12390 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
123a0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
123b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
123c0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
123d0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
123e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
123f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12400 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12410 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12420 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
12430 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
12440 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12450 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12460 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12470 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12480 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12490 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
124a0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
124b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
124c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
124d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
124e0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
124f0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
12500 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
12510 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12520 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
12530 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12540 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
12550 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
12560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12570 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12580 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12590 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
125a0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
125b0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
125c0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
125d0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
125e0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
125f0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
12600 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12610 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
12620 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
12630 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
12640 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
12650 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
12660 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12670 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12680 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
12690 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
126a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
126b0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
126c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
126d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
126e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
126f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
12700 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12720 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
12730 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12740 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
12750 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12760 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12770 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12780 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12790 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
127a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
127b0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
127c0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
127d0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
127e0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
127f0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
12800 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
12810 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
12820 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
12830 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
12840 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
12850 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
12860 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
12870 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
12880 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
12890 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
128a0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
128b0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
128c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
128d0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
128e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
128f0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
12900 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
12910 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12920 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
12930 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
12940 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
12950 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
12960 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
12970 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
12980 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
12990 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
129a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
129b0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
129c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
129d0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
129e0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
129f0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
12a00 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
12a10 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
12a20 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
12a30 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12a40 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
12a50 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12a60 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
12a70 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
12a80 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
12a90 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
12aa0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12ab0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
12ac0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12ae0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12af0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12b00 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12b10 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12b20 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12b30 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
12b40 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
12b50 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
12b60 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12b70 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
12b80 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
12b90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12ba0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12bb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12bc0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12bd0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12be0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12bf0 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
12c00 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12c10 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
12c20 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
12c30 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
12c40 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
12c50 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12c60 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
12c70 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
12c80 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
12c90 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
12ca0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
12cb0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
12cc0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
12cd0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
12ce0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
12cf0 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
12d00 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
12d10 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
12d20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
12d30 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
12d40 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
12d50 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
12d60 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12d70 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12d80 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12d90 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12da0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12db0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
12dc0 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
12dd0 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
12de0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
12df0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12e00 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
12e10 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12e20 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
12e30 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
12e40 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
12e50 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
12e60 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12e70 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12e80 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12e90 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12ea0 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12eb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12ec0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12ed0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12ee0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12ef0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12f00 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
12f10 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
12f20 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
12f30 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
12f40 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
12f50 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12f60 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
12f70 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
12f80 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
12f90 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
12fa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
12fb0 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
12fc0 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
12fd0 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
12fe0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
12ff0 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
13000 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
13010 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
13020 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
13030 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
13040 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13050 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
13060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13070 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
13080 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13090 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
130a0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
130b0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
130c0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
130d0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
130e0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
130f0 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
13100 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
13110 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
13120 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
13130 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13140 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
13150 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
13160 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
13170 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
13180 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
13190 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
131a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
131b0 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67  ACHE2].** config
131c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a  uration option..
131d0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
131e0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
131f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13200 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
13210 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
13220 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
13230 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
13240 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
13250 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
13260 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
13270 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
13280 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
13290 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
132a0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
132b0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
132c0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
132d0 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
132e0 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
132f0 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
13300 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
13310 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
13320 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
13330 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
13340 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
13350 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
13360 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
13370 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
13380 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20  ] option .** to 
13390 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
133a0 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  )]..** ^It is ha
133b0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
133c0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
133d0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
133e0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
133f0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13400 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13410 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
13420 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72  t should pointer
13430 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
13440 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
13450 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73  emory that.** is
13460 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
13470 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
13480 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71  otherwise subseq
13490 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
134a0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
134b0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
134c0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
134d0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
134e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
134f0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
13500 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
13510 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
13520 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
13530 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
13540 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
13550 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
13560 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
13570 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
13580 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
13590 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
135a0 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
135b0 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
135c0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
135d0 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e  rage space.</dd>
135e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
135f0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
13600 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13610 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
13620 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13630 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
13640 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13650 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13660 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
13670 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
13680 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
13690 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
136a0 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
136b0 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
136c0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
136d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
136e0 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
136f0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13700 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
13710 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
13720 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
13730 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
13740 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
13750 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
13760 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
13770 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
13780 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
13790 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
137a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
137b0 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
137c0 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
137d0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
137e0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
137f0 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
13800 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
13810 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
13820 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
13830 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
13840 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
13850 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
13860 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13870 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
13880 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
13890 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
138a0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
138b0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
138c0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
138d0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
138e0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
138f0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
13900 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
13910 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
13920 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
13930 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13940 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
13950 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
13960 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
13970 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
13980 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
13990 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
139a0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
139b0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
139c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
139d0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
139e0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
139f0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
13a00 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13a10 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
13a20 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
13a30 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
13a40 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
13a50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
13a60 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13a70 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
13a80 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
13a90 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
13aa0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
13ab0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13ac0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
13ad0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
13ae0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13af0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
13b00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13b10 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13b20 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13b30 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
13b40 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13b50 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13b60 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
13b70 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13b80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13b90 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13ba0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
13bb0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13bc0 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
13bd0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
13be0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13bf0 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
13c00 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
13c10 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
13c20 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
13c30 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
13c40 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
13c50 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13c60 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13c70 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
13c80 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
13c90 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13ca0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
13cb0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13cc0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13cd0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13ce0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13cf0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13d00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13d10 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13d20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13d30 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13d40 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
13d50 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
13d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13d70 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
13d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13d90 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13da0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13db0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13dc0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13dd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13de0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
13df0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13e00 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
13e10 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13e20 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13e30 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
13e40 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13e50 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
13e60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13e70 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13e80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13e90 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
13ea0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
13eb0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
13ec0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13ed0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13ee0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
13ef0 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
13f00 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13f10 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13f20 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13f30 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
13f40 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
13f50 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
13f60 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
13f70 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
13f80 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
13f90 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
13fa0 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
13fb0 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
13fc0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13fd0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13fe0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13ff0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14000 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14010 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
14020 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
14030 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
14040 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14050 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14060 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14070 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14080 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14090 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
140a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
140b0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
140c0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
140d0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
140e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
140f0 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
14100 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14110 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
14120 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14130 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14140 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14150 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
14160 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
14170 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
14180 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
14190 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
141a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
141b0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
141c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
141d0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
141e0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
141f0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14200 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14210 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14220 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
14230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14240 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
14250 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14260 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
14270 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
14280 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
14290 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
142a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
142b0 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
142c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
142d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
142e0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
142f0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
14300 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
14310 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
14320 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14340 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14350 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14360 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14370 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14380 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
14390 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
143a0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
143b0 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
143c0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
143d0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
143e0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
143f0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14400 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14410 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14420 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14430 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
14440 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14450 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
14460 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14470 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
14480 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14490 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
144a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
144b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
144c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
144d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
144e0 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
144f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14500 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14510 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14520 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14530 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14540 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
14550 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
14560 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
14570 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14580 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
14590 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
145a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
145b0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
145c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
145d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
145e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
145f0 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
14600 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
14610 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
14620 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
14630 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
14640 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14650 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14660 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
14670 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
14680 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
14690 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
146a0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
146b0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
146c0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
146d0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
146e0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
146f0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
14700 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
14710 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14720 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
14730 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
14740 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
14750 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
14760 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
14770 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
14780 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
14790 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
147a0 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
147b0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
147c0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
147d0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
147e0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
147f0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
14800 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
14810 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14820 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14830 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
14840 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
14850 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
14860 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
14870 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
14880 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
14890 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
148a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
148b0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
148c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
148d0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
148e0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
148f0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
14900 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
14910 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
14920 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
14930 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
14940 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
14950 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
14960 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
14970 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
14980 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
14990 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
149a0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
149b0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
149c0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
149d0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
149e0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
149f0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
14a00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14a10 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
14a20 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
14a30 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
14a40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14a50 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14a60 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
14a70 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
14a80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14a90 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
14aa0 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
14ab0 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
14ac0 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
14ad0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14ae0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14af0 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
14b00 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
14b10 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14b20 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
14b30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
14b40 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
14b50 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14b60 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14b70 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
14b80 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14b90 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
14ba0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
14bb0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
14bc0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
14bd0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
14be0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14bf0 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
14c00 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
14c10 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
14c20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
14c30 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
14c40 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
14c50 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
14c60 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
14c70 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
14c80 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
14c90 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14ca0 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
14cb0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14cc0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
14cd0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
14ce0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
14cf0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
14d00 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
14d10 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
14d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14d30 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
14d40 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
14d50 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14d60 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
14d70 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
14d80 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
14d90 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
14da0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
14db0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
14dc0 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
14dd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14de0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14df0 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
14e00 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14e10 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
14e20 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
14e30 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14e40 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
14e50 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14e60 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
14e70 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14e80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14e90 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14ea0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14eb0 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
14ec0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14ed0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
14ee0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
14ef0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
14f00 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14f10 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
14f20 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
14f30 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14f40 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14f50 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14f60 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14f70 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14f80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14f90 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14fa0 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14fb0 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14fc0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14fd0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
14fe0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
14ff0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
15000 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
15010 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
15020 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
15030 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
15040 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
15050 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
15060 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
15070 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
15080 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15090 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
150a0 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
150b0 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
150c0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
150d0 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
150e0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
150f0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
15100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15110 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
15120 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15130 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15140 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
15150 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
15160 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
15170 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
15180 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
15190 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
151a0 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
151b0 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
151c0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
151d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
151e0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
151f0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
15200 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15210 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
15220 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15230 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
15240 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
15250 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15260 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
15270 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15280 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
15290 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
152a0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
152b0 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
152c0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
152d0 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
152e0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
152f0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
15300 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
15310 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
15320 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
15330 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
15340 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
15350 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15360 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
15370 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
15380 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
15390 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
153a0 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
153b0 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
153c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
153d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
153e0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
153f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15400 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15410 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15420 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
15430 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
15440 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
15450 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
15460 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
15470 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
15480 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
15490 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
154a0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
154b0 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
154c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
154d0 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
154e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
154f0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15500 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15510 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15520 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
15530 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
15540 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
15550 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15560 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15570 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
15580 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
15590 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
155a0 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
155b0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
155c0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
155d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
155e0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
155f0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
15600 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
15610 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
15620 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
15630 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
15640 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15650 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
15660 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15670 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15680 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
15690 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
156a0 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
156b0 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
156c0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
156d0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
156e0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
156f0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
15700 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
15710 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
15720 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
15730 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15740 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
15750 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15760 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
15770 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
15780 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
15790 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
157a0 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
157b0 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
157c0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
157d0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
157e0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
157f0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
15800 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
15810 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15820 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
15830 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
15840 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
15850 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
15860 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
15870 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
15880 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
15890 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
158a0 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
158b0 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
158c0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
158d0 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
158e0 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
158f0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15900 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15910 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15920 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
15930 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
15940 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15950 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15960 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15970 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15980 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
15990 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
159a0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
159b0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
159c0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
159d0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
159e0 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
159f0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
15a00 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
15a10 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15a20 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
15a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15a40 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
15a50 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
15a60 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
15a70 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
15a80 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
15a90 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
15aa0 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
15ab0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15ac0 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
15ad0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15ae0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
15af0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15b00 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15b10 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
15b20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
15b30 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
15b40 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15b50 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
15b60 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
15b70 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
15b80 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
15b90 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
15ba0 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
15bb0 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
15bc0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15bd0 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
15be0 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
15bf0 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
15c00 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
15c10 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
15c20 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
15c30 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
15c40 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
15c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15c60 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
15c70 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
15c80 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15c90 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
15ca0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15cb0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15cc0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
15cd0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15ce0 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
15cf0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
15d00 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
15d10 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
15d20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
15d30 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
15d40 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
15d50 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
15d60 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
15d70 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
15d80 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
15d90 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
15da0 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
15db0 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
15dc0 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
15dd0 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
15de0 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
15df0 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
15e00 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
15e10 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
15e20 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
15e30 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
15e40 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
15e50 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
15e60 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
15e70 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
15e80 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
15e90 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f  his value..** </
15ea0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
15eb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15ec0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
15ed0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
15ee0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15ef0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
15f00 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15f10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15f20 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
15f30 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15f40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15f50 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
15f60 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
15f70 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
15f80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15f90 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
15fa0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
15fb0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15fd0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
15fe0 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
15ff0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
16000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16010 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
16020 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
16030 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16040 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16050 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
16060 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
16070 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
16080 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
16090 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
160a0 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
160b0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
160c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
160d0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
160e0 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
160f0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
16100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16110 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16120 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
16130 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16140 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
16150 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
16160 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
16170 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
16180 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
16190 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
161a0 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
161b0 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
161c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
161d0 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
161e0 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
161f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16200 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16210 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
16220 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16230 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
16240 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
16250 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
16260 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16270 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
16280 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
16290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
162a0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
162b0 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
162c0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
162d0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
162e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
162f0 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
16300 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16310 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
16320 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16330 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
16340 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
16350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16360 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
16370 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
16380 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
16390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
163a0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
163b0 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
163c0 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
163d0 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
163e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
163f0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
16400 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
16410 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
16420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16430 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
16440 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
16450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16460 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
16470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
16480 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
16490 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a  t szPma */../*.*
164a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
164b0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
164c0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
164d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
164e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
164f0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
16500 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
16510 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
16520 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
16530 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16540 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
16550 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16560 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
16570 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
16580 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16590 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
165a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
165b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
165c0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
165d0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
165e0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
165f0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
16600 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
16610 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
16620 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
16630 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
16640 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
16650 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
16660 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
16670 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16680 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
16690 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
166a0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
166b0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
166c0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
166d0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
166e0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
166f0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
16700 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16710 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16720 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
16730 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
16740 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
16750 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
16760 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
16770 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
16780 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
16790 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
167a0 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
167b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
167c0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
167d0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
167e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
167f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16800 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
16810 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
16820 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
16830 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16840 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
16850 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
16860 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
16870 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
16880 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
16890 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
168a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
168b0 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
168c0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
168d0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
168e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
168f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16900 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
16910 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
16920 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
16930 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
16940 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
16950 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
16960 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
16970 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
16980 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
16990 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
169a0 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
169b0 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
169c0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
169d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
169e0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
169f0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
16a00 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
16a10 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
16a20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16a30 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
16a40 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16a50 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
16a60 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
16a70 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
16a80 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
16a90 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
16aa0 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
16ab0 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
16ac0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
16ad0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
16ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16af0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
16b00 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
16b10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
16b20 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
16b30 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
16b40 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
16b50 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
16b60 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
16b70 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
16b80 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
16b90 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
16ba0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16bb0 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
16bc0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
16bd0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16be0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
16bf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
16c00 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
16c10 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
16c20 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
16c30 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
16c40 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
16c50 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
16c60 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
16c70 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16c80 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
16c90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16ca0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16cb0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16cc0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
16cd0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
16ce0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
16cf0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
16d00 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16d10 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16d20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16d30 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16d40 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16d50 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
16d60 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
16d70 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16d80 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16d90 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16da0 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16db0 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
16dc0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16dd0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16de0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16df0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
16e00 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16e10 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16e20 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
16e30 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
16e40 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
16e50 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16e60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16e70 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16e80 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16e90 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16ea0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16eb0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16ec0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16ed0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16ee0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16ef0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
16f00 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16f10 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16f20 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16f30 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16f40 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
16f50 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16f60 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16f70 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16f80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16f90 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16fa0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16fb0 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
16fc0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16fd0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
16fe0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16ff0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
17000 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
17010 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17020 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17030 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17040 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17050 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17060 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17070 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17080 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17090 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
170a0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
170b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
170c0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
170d0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
170e0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
170f0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17100 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17110 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
17120 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
17130 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17140 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
17150 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
17160 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17170 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17180 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
17190 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
171a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
171b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
171c0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
171d0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
171e0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
171f0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
17200 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
17210 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d  esult Codes.** M
17220 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
17230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17240 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
17250 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
17260 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
17270 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
17280 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
17290 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
172a0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
172b0 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
172c0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
172d0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
172e0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
172f0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
17300 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
17310 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
17320 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
17330 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
17340 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
17350 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54  ert Rowid.** MET
17360 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
17370 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
17380 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
17390 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
173a0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
173b0 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
173c0 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
173d0 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
173e0 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
173f0 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
17400 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
17410 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
17420 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
17430 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
17440 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
17450 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
17460 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
17470 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
17480 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
17490 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
174a0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
174b0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
174c0 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
174d0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
174e0 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
174f0 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
17500 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
17510 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
17520 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
17530 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
17540 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17550 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
17560 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63  the .** most rec
17570 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
17580 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
17590 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
175a0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
175b0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
175c0 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49  nection D..** ^I
175d0 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
175e0 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
175f0 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72  es are not recor
17600 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  ded..** ^If no s
17610 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17620 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
17630 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76  ables.** have ev
17640 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
17650 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17660 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68  ection D, .** th
17670 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
17680 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
17690 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
176a0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
176b0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
176c0 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
176d0 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
176e0 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
176f0 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
17700 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
17710 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
17720 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
17730 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
17740 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
17750 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
17760 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
17770 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
17780 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17790 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
177a0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
177b0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
177c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
177d0 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
177e0 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
177f0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
17800 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
17810 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
17820 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
17830 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
17840 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
17850 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
17860 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
17870 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
17880 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
17890 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
178a0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
178b0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
178c0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
178d0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
178e0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
178f0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
17900 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
17910 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
17920 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
17930 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
17940 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
17950 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
17960 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
17970 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
17980 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
17990 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
179a0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
179b0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
179c0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
179d0 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
179e0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
179f0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
17a00 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
17a10 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
17a20 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
17a30 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
17a40 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
17a50 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
17a60 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
17a70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
17a80 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
17a90 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
17aa0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
17ab0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
17ac0 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
17ad0 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
17ae0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
17af0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
17b00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17b10 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
17b20 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
17b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
17b40 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
17b50 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
17b60 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
17b70 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
17b80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17b90 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
17ba0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17bb0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
17bc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
17bd0 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
17be0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
17bf0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
17c00 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
17c10 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
17c20 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17c30 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
17c40 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17c50 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
17c60 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
17c70 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
17c80 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
17c90 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
17ca0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
17cb0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
17cc0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17cd0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
17ce0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
17cf0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
17d00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
17d10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
17d20 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17d30 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
17d40 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
17d50 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
17d60 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
17d70 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
17d80 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
17d90 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
17da0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
17db0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17dc0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
17dd0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
17de0 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
17df0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
17e00 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
17e10 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
17e20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
17e30 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
17e40 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
17e50 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
17e60 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
17e70 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
17e80 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
17e90 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
17ea0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
17eb0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
17ec0 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
17ed0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
17ee0 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
17ef0 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
17f00 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
17f10 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
17f20 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
17f30 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
17f40 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
17f50 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
17f60 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
17f70 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
17f80 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
17f90 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
17fa0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
17fb0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
17fc0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
17fd0 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
17fe0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
17ff0 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
18000 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
18010 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
18020 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
18030 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
18040 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
18050 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
18060 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
18070 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
18080 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
18090 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
180a0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
180b0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
180c0 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
180d0 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
180e0 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
180f0 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
18100 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18110 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
18120 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
18130 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
18140 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
18150 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
18160 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
18170 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
18180 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
18190 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
181a0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
181b0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
181c0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
181d0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
181e0 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
181f0 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
18200 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
18210 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
18220 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
18230 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
18240 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
18250 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
18260 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
18270 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
18280 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
18290 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
182a0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
182b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
182c0 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
182d0 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
182e0 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
182f0 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
18300 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
18310 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
18320 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
18330 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
18340 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
18350 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18360 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
18370 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
18380 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
18390 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
183a0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
183b0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
183c0 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
183d0 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
183e0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
183f0 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
18400 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
18410 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
18420 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
18430 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
18440 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
18450 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
18460 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
18470 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
18480 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
18490 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
184a0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
184b0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
184c0 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
184d0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
184e0 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
184f0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18500 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
18510 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
18520 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
18530 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
18540 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
18550 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
18560 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
18570 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
18580 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
18590 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
185a0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
185b0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
185c0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
185d0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
185e0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
185f0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18600 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
18610 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
18620 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
18630 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
18640 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
18650 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18660 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18670 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
18680 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18690 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
186a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
186b0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
186c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
186d0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
186e0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
186f0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
18700 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
18710 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
18720 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
18730 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
18740 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
18750 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
18760 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
18770 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
18780 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
18790 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
187a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
187b0 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
187c0 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
187d0 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
187e0 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
187f0 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
18800 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
18810 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
18820 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
18830 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
18840 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18850 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
18860 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
18870 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
18880 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
18890 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
188a0 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
188b0 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
188c0 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
188d0 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
188e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
188f0 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
18900 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
18910 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
18920 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
18930 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
18940 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
18950 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
18960 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
18970 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
18980 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
18990 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
189a0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
189b0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
189c0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
189d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
189e0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
189f0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
18a00 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
18a10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
18a20 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
18a30 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
18a40 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
18a50 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
18a60 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
18a70 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
18a80 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
18a90 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18aa0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
18ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18ac0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
18ad0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
18ae0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
18af0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
18b00 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
18b10 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
18b20 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
18b30 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
18b40 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
18b50 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
18b60 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
18b70 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
18b80 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
18b90 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
18ba0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
18bb0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
18bc0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
18bd0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
18be0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
18bf0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
18c00 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
18c10 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
18c20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
18c30 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
18c40 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
18c50 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
18c60 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
18c70 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
18c80 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
18c90 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
18ca0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
18cb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
18cc0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
18cd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
18ce0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
18cf0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
18d00 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
18d10 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
18d20 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
18d30 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
18d40 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
18d50 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
18d60 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
18d70 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
18d80 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
18d90 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
18da0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
18db0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
18dc0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
18dd0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
18de0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
18df0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
18e00 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
18e10 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
18e20 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
18e30 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
18e40 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
18e50 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
18e60 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
18e70 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
18e80 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
18e90 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
18ea0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
18eb0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
18ec0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
18ed0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
18ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18ef0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
18f00 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
18f10 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
18f20 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
18f30 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
18f40 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
18f50 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
18f60 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
18f70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
18f80 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
18f90 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
18fa0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18fb0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
18fc0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
18fd0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
18fe0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
18ff0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
19000 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
19010 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
19020 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
19030 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
19040 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
19050 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
19060 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
19070 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
19080 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
19090 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
190a0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
190b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
190c0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
190d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
190e0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
190f0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
19100 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
19110 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19120 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
19130 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
19140 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
19150 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
19160 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
19170 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19180 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
19190 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
191a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
191b0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
191c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
191d0 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
191e0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
191f0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
19200 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
19210 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19220 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19230 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
19240 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
19250 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
19260 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
19270 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19280 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
19290 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
192a0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
192b0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
192c0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
192d0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
192e0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
192f0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
19300 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
19310 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
19320 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
19330 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
19340 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
19350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19360 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
19370 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
19380 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
19390 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
193a0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
193b0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
193c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
193d0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
193e0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
193f0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
19400 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
19410 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
19420 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
19430 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
19440 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
19450 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
19460 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
19470 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
19480 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
19490 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
194a0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
194b0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
194c0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
194d0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
194e0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
194f0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
19500 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
19510 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
19520 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
19530 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
19540 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
19550 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
19560 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
19570 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19580 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
19590 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
195a0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
195b0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
195c0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
195d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
195e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
195f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19600 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
19610 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19620 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
19630 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
19640 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
19650 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
19660 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
19670 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
19680 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
19690 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
196a0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
196b0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
196c0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
196d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
196e0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
196f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
19700 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19710 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
19720 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
19730 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
19740 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
19750 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
19760 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
19770 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
19780 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
19790 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
197a0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
197b0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
197c0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
197d0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
197e0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
197f0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19800 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
19810 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
19820 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19830 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
19840 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19850 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
19860 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
19870 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
19880 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
19890 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
198a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
198b0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
198c0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
198d0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
198e0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
198f0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
19900 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
19910 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
19920 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
19930 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
19940 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19960 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19970 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
19980 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
19990 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
199a0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
199b0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
199c0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
199d0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
199e0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
199f0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
19a00 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
19a10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19a20 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
19a30 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
19a40 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
19a50 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
19a60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19a70 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
19a80 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
19a90 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
19aa0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
19ab0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
19ac0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
19ad0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
19ae0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19af0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
19b00 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
19b10 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
19b20 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
19b30 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
19b40 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
19b50 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
19b60 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
19b70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
19b80 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19b90 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
19ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
19bb0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19bc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19bd0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
19be0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
19bf0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
19c00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
19c10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19c20 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
19c30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
19c40 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
19c50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
19c60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
19c70 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
19c80 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
19c90 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
19ca0 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
19cb0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
19cc0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
19cd0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
19ce0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
19cf0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
19d00 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
19d10 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
19d20 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
19d30 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
19d40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
19d50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
19d60 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
19d70 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19d80 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
19d90 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19da0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
19db0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19dc0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
19dd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
19de0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
19df0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
19e00 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
19e10 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
19e20 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
19e30 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
19e40 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
19e50 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
19e60 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
19e70 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
19e80 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
19e90 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
19ea0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
19eb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
19ec0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
19ed0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
19ee0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
19ef0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
19f00 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
19f10 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
19f20 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
19f30 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
19f40 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
19f50 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
19f60 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
19f70 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
19f80 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
19f90 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
19fa0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
19fb0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
19fc0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
19fd0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
19fe0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
19ff0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1a000 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1a010 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1a020 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1a030 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1a040 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1a050 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1a060 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1a070 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1a080 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1a090 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1a0a0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1a0b0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1a0c0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1a0d0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1a0e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1a0f0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1a100 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1a110 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1a120 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1a130 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1a140 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1a150 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1a160 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1a170 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1a180 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1a190 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1a1a0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1a1b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1a1c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1a1d0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1a1e0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1a1f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a200 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1a210 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1a220 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1a230 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1a240 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1a250 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1a260 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1a270 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1a280 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1a290 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1a2a0 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1a2b0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1a2c0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1a2d0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1a2e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a2f0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1a300 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1a310 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1a320 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1a330 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1a340 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1a350 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1a360 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1a370 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1a380 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1a390 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1a3a0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1a3b0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1a3c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1a3d0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1a3e0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1a3f0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1a400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a410 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1a420 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1a430 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1a440 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
1a450 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1a460 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1a470 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1a480 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
1a490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1a4a0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1a4b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a4c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1a4d0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1a4e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a4f0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1a500 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1a510 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1a520 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1a530 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1a540 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1a550 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1a560 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1a570 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1a580 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1a590 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1a5a0 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1a5b0 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1a5c0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1a5d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1a5e0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1a5f0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1a600 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1a610 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1a620 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1a630 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1a640 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1a650 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1a660 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1a670 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1a680 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1a690 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1a6a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1a6b0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1a6c0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1a6d0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1a6e0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1a6f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1a700 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1a710 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1a720 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1a730 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1a740 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1a750 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1a760 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1a770 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1a780 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1a790 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1a7a0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1a7b0 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1a7c0 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
1a7d0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1a7e0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1a7f0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1a800 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1a810 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1a820 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1a830 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1a840 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1a850 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1a860 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1a870 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1a880 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1a890 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1a8a0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1a8b0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1a8c0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1a8d0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1a8e0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1a8f0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1a900 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1a910 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1a920 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1a930 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1a940 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1a950 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1a960 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1a970 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1a980 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1a990 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1a9a0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1a9b0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1a9c0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1a9d0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1a9e0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1a9f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1aa00 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1aa10 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1aa20 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1aa30 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1aa40 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1aa50 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1aa60 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1aa70 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1aa80 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1aa90 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1aaa0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1aab0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1aac0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1aad0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1aae0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1aaf0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1ab00 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1ab10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1ab20 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1ab30 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1ab40 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1ab50 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1ab60 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1ab70 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1ab80 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1ab90 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1aba0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1abb0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1abc0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1abd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1abe0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1abf0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1ac00 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1ac10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1ac20 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1ac30 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1ac40 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1ac50 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1ac60 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1ac70 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1ac80 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1ac90 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1aca0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1acb0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1acc0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1acd0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1ace0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1acf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1ad00 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1ad10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1ad20 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1ad30 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1ad40 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1ad50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ad60 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1ad70 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1ad80 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1ad90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ada0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1adb0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1adc0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1add0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1ade0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1adf0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1ae00 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ae10 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1ae20 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1ae30 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1ae40 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1ae50 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1ae60 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1ae70 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1ae80 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1ae90 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1aea0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1aeb0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1aec0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1aed0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1aee0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1aef0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1af00 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1af10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1af20 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1af30 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1af40 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1af50 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1af60 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1af70 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1af80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1af90 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1afa0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1afb0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1afc0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1afd0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1afe0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1aff0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1b000 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1b010 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1b020 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b030 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1b040 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1b050 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1b060 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1b070 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1b080 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1b090 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1b0a0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1b0b0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1b0c0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1b0d0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1b0e0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1b0f0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1b100 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1b110 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1b120 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1b130 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1b140 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1b150 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1b160 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1b170 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1b180 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1b190 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1b1a0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1b1b0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1b1c0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1b1d0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1b1e0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1b1f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1b200 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1b210 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b220 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1b230 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1b240 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1b250 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b260 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1b270 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1b280 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1b290 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1b2a0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1b2b0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1b2c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1b2d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1b2e0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1b2f0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1b300 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1b310 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1b320 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1b330 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1b340 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1b350 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1b360 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1b370 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1b380 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1b390 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1b3a0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1b3b0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1b3c0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1b3d0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1b3e0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1b3f0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1b400 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1b410 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1b420 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1b430 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1b440 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1b450 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1b460 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1b470 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1b480 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1b490 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1b4a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1b4b0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1b4c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1b4d0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1b4e0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1b4f0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1b500 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1b510 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1b520 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1b530 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1b540 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1b550 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1b560 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1b570 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1b580 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1b590 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1b5a0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1b5b0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1b5c0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1b5d0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1b5e0 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1b5f0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1b600 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1b610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b620 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1b630 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1b640 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1b650 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1b660 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1b670 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1b680 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1b690 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1b6a0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1b6b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b6c0 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1b6d0 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b   of the common K
1b6e0 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  &R formatting op
1b6f0 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73  tions,.** plus s
1b700 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1b710 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1b720 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65  ats, detailed be
1b730 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  low..** Note tha
1b740 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f  t some of the mo
1b750 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61  re obscure forma
1b760 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
1b770 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c  om recent.** C-l
1b780 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73  ibrary standards
1b790 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f   are omitted fro
1b7a0 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74  m this implement
1b7b0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
1b7c0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1b7d0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1b7e0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1b7f0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1b800 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1b810 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1b820 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1b830 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1b840 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1b850 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1b860 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1b870 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1b880 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b890 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1b8a0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1b8b0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1b8c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b8d0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1b8e0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1b8f0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1b900 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1b910 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1b920 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1b930 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1b940 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1b950 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1b960 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1b970 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1b980 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1b990 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1b9a0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1b9b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1b9c0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1b9d0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1b9e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1b9f0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1ba00 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1ba10 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1ba20 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1ba30 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1ba40 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1ba50 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1ba60 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1ba70 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1ba80 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1ba90 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1baa0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1bab0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1bac0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1bad0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1bae0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1baf0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1bb00 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1bb10 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1bb20 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1bb30 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1bb40 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1bb50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1bb60 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1bb70 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1bb80 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1bb90 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1bba0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1bbb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1bbc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1bbd0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1bbe0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1bbf0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1bc00 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1bc10 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1bc20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1bc30 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1bc40 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1bc50 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1bc60 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1bc70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1bc80 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1bc90 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1bca0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1bcb0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1bcc0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1bcd0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1bce0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1bcf0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1bd00 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1bd10 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1bd20 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1bd30 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1bd40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1bd50 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1bd60 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1bd70 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1bd80 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1bd90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1bda0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1bdb0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1bdc0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1bdd0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1bde0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1bdf0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1be00 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1be10 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1be20 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1be30 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1be40 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1be50 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1be60 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64  , "%Q", "%w" and
1be70 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1be80 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1be90 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1bea0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1beb0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1bec0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1bed0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1bee0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1bef0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1bf00 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1bf10 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1bf20 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1bf30 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1bf40 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1bf50 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1bf60 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1bf70 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1bf80 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1bf90 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1bfa0 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1bfb0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1bfc0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1bfd0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1bfe0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1bff0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1c000 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c010 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c020 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1c030 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1c040 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1c050 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c060 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1c070 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1c080 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1c090 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1c0a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c0b0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1c0c0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1c0d0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1c0e0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1c0f0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1c100 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1c110 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1c120 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1c130 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1c140 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c150 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1c160 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1c170 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1c180 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1c190 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1c1a0 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1c1b0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1c1c0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1c1d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c1e0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1c1f0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1c200 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1c210 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1c220 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1c230 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1c240 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1c250 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1c260 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1c270 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1c280 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1c290 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1c2a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c2b0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1c2c0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1c2d0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1c2e0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1c2f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c300 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1c310 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1c320 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1c330 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1c340 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1c350 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1c360 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1c370 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1c380 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1c390 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1c3a0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1c3b0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1c3c0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1c3d0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1c3e0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1c3f0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1c400 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1c410 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1c420 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1c430 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1c440 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c450 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1c460 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1c470 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1c480 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1c490 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1c4a0 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1c4b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c4c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1c4d0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1c4e0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1c4f0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1c500 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1c510 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1c520 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1c530 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1c540 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1c550 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c560 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1c570 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1c580 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1c590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1c5a0 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1c5b0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1c5c0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1c5d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1c5e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1c5f0 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1c600 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22  option is like "
1c610 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20  %q" except that 
1c620 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a  it expects to.**
1c630 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69   be contained wi
1c640 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  thin double-quot
1c650 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
1c660 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64  ngle quotes, and
1c670 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74   it.** escapes t
1c680 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20  he double-quote 
1c690 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61  character instea
1c6a0 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d  d of the single-
1c6b0 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74  quote.** charact
1c6c0 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20  er.)^  The "%w" 
1c6d0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c6e0 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  n is intended fo
1c6f0 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69  r safely inserti
1c700 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20  ng.** table and 
1c710 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74  column names int
1c720 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20  o a constructed 
1c730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1c740 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1c750 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c760 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1c770 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1c780 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1c790 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1c7a0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1c7b0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1c7c0 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1c7d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1c7e0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1c7f0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1c800 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1c810 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1c820 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1c830 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1c840 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1c850 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1c860 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1c870 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1c880 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1c890 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1c8a0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1c8b0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1c8c0 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1c8d0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1c8e0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1c8f0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1c900 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1c910 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1c920 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1c930 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1c940 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1c950 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1c960 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1c970 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1c980 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1c990 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1c9a0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1c9b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1c9c0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1c9d0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1c9e0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1c9f0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1ca00 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1ca10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ca20 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1ca30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1ca40 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1ca50 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1ca60 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1ca70 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1ca80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1ca90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1caa0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1cab0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1cac0 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1cad0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1cae0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1caf0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1cb00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1cb10 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1cb20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1cb30 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1cb40 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1cb50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1cb60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cb70 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1cb80 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1cb90 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1cba0 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1cbb0 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1cbc0 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1cbd0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1cbe0 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1cbf0 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1cc00 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1cc10 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1cc20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1cc30 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1cc40 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1cc50 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1cc60 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1cc70 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1cc80 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1cc90 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1cca0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1ccb0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1ccc0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1ccd0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1cce0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1ccf0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1cd00 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1cd10 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1cd20 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1cd30 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1cd40 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1cd50 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1cd60 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1cd70 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1cd80 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1cd90 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1cda0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1cdb0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1cdc0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1cdd0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1cde0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1cdf0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1ce00 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1ce10 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1ce20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1ce30 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1ce40 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1ce50 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1ce60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1ce70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ce80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1ce90 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1cea0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ceb0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1cec0 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1ced0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1cee0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1cef0 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1cf00 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1cf10 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1cf20 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1cf30 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1cf40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1cf50 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1cf60 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1cf70 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1cf80 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1cf90 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1cfa0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1cfb0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1cfc0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1cfd0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1cfe0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1cff0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1d000 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1d010 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1d020 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d030 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1d040 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1d050 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1d060 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1d070 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1d080 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1d090 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1d0a0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1d0b0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1d0c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d0d0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1d0e0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1d0f0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d100 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1d110 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1d120 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1d130 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1d140 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1d150 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1d160 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1d170 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1d180 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1d190 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1d1a0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1d1b0 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1d1c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1d1d0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1d1e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1d1f0 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1d200 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1d210 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1d220 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d230 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1d240 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1d250 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1d260 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1d270 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1d280 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1d290 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1d2a0 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1d2b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1d2c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1d2d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d2e0 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1d2f0 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1d300 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1d310 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1d320 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1d330 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1d340 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1d350 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1d360 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1d370 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d380 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1d390 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1d3a0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1d3b0 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1d3c0 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1d3d0 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1d3e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1d3f0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1d400 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1d410 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1d420 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1d430 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1d440 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1d450 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1d460 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1d470 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1d480 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1d490 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1d4a0 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1d4b0 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1d4c0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1d4d0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d4e0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1d4f0 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1d500 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1d510 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1d520 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d530 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1d540 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1d550 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1d560 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d570 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1d580 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1d590 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1d5a0 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1d5b0 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1d5c0 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1d5d0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1d5e0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1d5f0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1d600 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1d610 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1d620 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1d630 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1d640 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1d650 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1d660 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1d670 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1d680 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1d690 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1d6a0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1d6b0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1d6c0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1d6d0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1d6e0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1d6f0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1d700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1d710 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1d720 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1d730 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1d740 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1d750 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1d760 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1d770 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1d780 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1d790 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1d7a0 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1d7b0 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1d7c0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1d7d0 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1d7e0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1d7f0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1d800 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1d810 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1d820 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1d830 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1d840 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1d850 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1d860 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1d870 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1d880 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1d890 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1d8a0 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1d8b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1d8c0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1d8d0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1d8e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1d8f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1d900 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1d910 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1d920 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1d930 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1d940 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1d950 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1d960 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1d970 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1d980 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1d990 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1d9a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1d9b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1d9c0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1d9d0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1d9e0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1d9f0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1da00 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1da10 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1da20 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1da30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1da40 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1da50 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1da60 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1da70 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1da80 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
1da90 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1daa0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
1dab0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1dac0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1dad0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
1dae0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1daf0 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
1db00 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
1db10 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1db20 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1db30 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1db40 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1db50 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1db60 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1db70 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1db80 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1db90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1dba0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1dbb0 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1dbc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1dbd0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1dbe0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1dbf0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1dc00 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1dc10 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1dc20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1dc30 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1dc40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1dc50 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1dc60 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1dc70 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1dc80 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1dc90 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1dca0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1dcb0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1dcc0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1dcd0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1dce0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1dcf0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1dd00 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1dd10 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1dd20 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1dd30 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1dd40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1dd50 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1dd60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1dd70 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1dd80 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1dd90 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1dda0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1ddb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1ddc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ddd0 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1dde0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1ddf0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1de00 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1de10 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1de20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1de30 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1de40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1de50 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1de60 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1de70 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1de80 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1de90 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1dea0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1deb0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1dec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1ded0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1dee0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1def0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1df00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1df10 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1df20 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1df30 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1df40 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1df50 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1df60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1df70 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1df80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1df90 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1dfa0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1dfb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dfc0 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1dfd0 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1dfe0 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1dff0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1e000 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1e010 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1e020 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1e030 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1e040 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1e050 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1e060 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1e070 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1e080 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1e090 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1e0a0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1e0b0 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1e0c0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1e0d0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1e0e0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1e0f0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1e100 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1e110 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1e120 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1e130 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1e140 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1e150 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1e160 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1e170 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1e180 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1e190 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1e1a0 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
1e1b0 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
1e1c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e1d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1e1e0 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1e1f0 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1e200 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1e210 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1e220 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1e230 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
1e240 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
1e250 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
1e260 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1e270 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1e280 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
1e290 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1e2a0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
1e2b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1e2c0 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
1e2d0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
1e2e0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
1e2f0 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
1e300 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
1e310 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
1e320 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1e330 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1e340 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1e350 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1e360 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1e370 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1e380 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1e390 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1e3a0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1e3b0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1e3c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1e3d0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1e3e0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1e3f0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1e400 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1e410 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1e420 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1e430 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1e440 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1e450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e460 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1e470 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1e480 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1e490 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e4a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1e4b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1e4c0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1e4d0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1e4e0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1e4f0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1e500 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e510 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1e520 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1e530 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e540 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1e550 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1e560 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1e570 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1e580 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1e590 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1e5a0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1e5b0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1e5c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e5d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1e5e0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1e5f0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1e600 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1e610 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e620 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1e630 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1e640 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1e650 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1e660 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1e670 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1e680 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1e690 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e6a0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1e6b0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1e6c0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1e6d0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1e6e0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1e6f0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1e700 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1e710 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1e720 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e730 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1e740 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1e750 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e760 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1e770 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1e780 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1e790 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e7a0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1e7b0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1e7c0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1e7d0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1e7e0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1e7f0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1e800 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1e810 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e820 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1e830 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1e840 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1e850 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1e860 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1e870 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1e880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1e890 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1e8a0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1e8b0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1e8c0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1e8d0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1e8e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1e8f0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1e900 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1e910 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1e920 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1e930 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1e940 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1e950 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1e960 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1e970 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1e980 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1e990 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1e9a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1e9b0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1e9c0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1e9d0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1e9e0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1e9f0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1ea00 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1ea10 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1ea20 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1ea30 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1ea40 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1ea50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1ea60 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1ea70 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1ea80 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1ea90 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1eaa0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1eab0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1eac0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1ead0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1eae0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1eaf0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1eb00 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1eb10 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1eb20 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1eb30 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1eb40 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1eb50 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1eb60 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1eb70 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1eb80 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1eb90 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1eba0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1ebb0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1ebc0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1ebd0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1ebe0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1ebf0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1ec00 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1ec10 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1ec20 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1ec30 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1ec40 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1ec50 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1ec60 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1ec70 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1ec80 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1ec90 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1eca0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1ecb0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1ecc0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1ecd0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1ece0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1ecf0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1ed00 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1ed10 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1ed20 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1ed30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1ed40 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1ed50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1ed60 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1ed70 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1ed80 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1ed90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1eda0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1edb0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1edc0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1edd0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1ede0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1edf0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1ee00 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1ee10 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1ee20 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1ee30 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1ee40 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1ee50 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1ee60 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1ee70 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1ee80 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1ee90 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1eea0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1eeb0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1eec0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1eed0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1eee0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1eef0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1ef00 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1ef10 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1ef20 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1ef30 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1ef40 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1ef50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1ef60 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1ef70 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1ef80 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1ef90 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1efa0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1efb0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1efc0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1efd0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1efe0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1eff0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1f000 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1f010 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1f020 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1f030 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1f040 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1f050 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1f060 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1f070 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1f080 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1f090 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1f0a0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1f0b0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1f0c0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1f0d0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1f0e0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1f0f0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1f100 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1f110 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1f120 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1f130 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1f140 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1f150 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1f160 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1f170 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1f180 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1f190 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1f1a0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1f1b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1f1c0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1f1d0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1f1e0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1f1f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1f200 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1f210 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f220 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1f230 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f240 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1f250 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1f260 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1f270 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f280 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1f290 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1f2a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1f2b0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1f2c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f2d0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1f2e0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1f2f0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1f300 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1f310 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1f320 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1f330 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1f340 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1f350 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1f360 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1f370 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1f380 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1f390 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f3a0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1f3b0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1f3c0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1f3d0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1f3e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f3f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1f400 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1f410 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f420 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1f430 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1f440 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1f450 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1f460 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1f470 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1f480 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1f490 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1f4a0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1f4b0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1f4c0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1f4d0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1f4e0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1f4f0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1f500 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1f510 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
1f520 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f530 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1f540 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1f550 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1f560 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1f570 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1f580 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1f590 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1f5a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f5b0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1f5c0 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1f5d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1f5e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1f5f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f600 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1f610 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1f620 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1f630 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1f640 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1f650 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1f660 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1f670 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1f680 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1f690 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1f6a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f6b0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1f6c0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1f6d0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1f6e0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1f6f0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1f700 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1f710 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1f720 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
1f730 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
1f740 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
1f750 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1f760 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1f770 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1f780 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1f790 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1f7a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1f7b0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1f7c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f7d0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1f7e0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1f7f0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1f800 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1f810 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1f820 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1f830 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1f840 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1f850 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1f860 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1f870 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1f880 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1f890 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1f8a0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1f8b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1f8c0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1f8d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1f8e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1f8f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1f900 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1f910 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1f920 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1f930 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1f940 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1f950 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1f960 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1f970 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1f980 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1f990 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1f9a0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1f9b0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1f9c0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1f9d0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1f9e0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1f9f0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1fa00 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1fa10 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1fa20 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1fa30 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1fa40 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1fa50 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1fa60 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1fa70 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1fa80 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1fa90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1faa0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1fab0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1fac0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1fad0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1fae0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1faf0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1fb00 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1fb10 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1fb20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1fb30 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1fb40 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1fb50 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1fb60 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1fb70 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1fb80 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1fb90 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1fba0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1fbb0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1fbc0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1fbd0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1fbe0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fbf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fc00 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1fc10 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1fc20 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1fc30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1fc40 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1fc50 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1fc60 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1fc70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fc80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1fc90 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1fca0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fcb0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fcc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fcd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1fce0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1fcf0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1fd00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1fd10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fd20 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1fd30 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1fd40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fd50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fd60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fd70 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1fd80 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1fd90 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1fda0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fdb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fdc0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1fdd0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1fde0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1fdf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fe00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fe10 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1fe20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1fe30 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1fe40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fe50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fe60 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1fe70 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1fe80 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1fe90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1feb0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1fec0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1fed0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1fee0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ff00 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1ff10 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1ff20 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1ff30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ff40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ff50 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1ff60 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1ff70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ff80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ff90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ffa0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1ffb0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1ffc0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ffd0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ffe0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1fff0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
20000 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
20010 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20020 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20030 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20040 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
20050 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
20060 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
20070 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20080 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
20090 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
200a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
200b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
200c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
200d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
200e0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
200f0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
20100 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
20110 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20120 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
20130 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
20140 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
20150 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20160 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20170 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
20180 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
20190 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
201a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
201b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
201c0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
201d0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
201e0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
201f0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
20200 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
20210 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
20220 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
20230 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20240 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
20250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20260 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
20270 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
20280 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20290 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
202a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
202b0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
202c0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
202d0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
202e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
202f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20300 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
20310 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
20320 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
20330 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
20340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20350 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
20360 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
20370 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
20380 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
203a0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
203b0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
203c0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
203d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
203e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
203f0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
20400 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
20410 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
20420 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
20440 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
20450 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
20460 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
20470 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20480 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
20490 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
204a0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
204b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
204c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
204d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
204e0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
204f0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
20500 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
20510 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20520 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
20530 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
20540 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
20550 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
20560 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20570 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
20580 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
20590 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
205a0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
205b0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
205c0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
205d0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
205e0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
205f0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
20600 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
20610 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
20620 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
20630 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
20640 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
20650 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
20660 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
20670 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
20680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20690 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
206a0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
206b0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
206c0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
206d0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
206e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
206f0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
20700 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
20710 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
20720 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
20730 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
20740 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
20750 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
20760 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
20770 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
20780 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
20790 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
207a0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
207b0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
207c0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
207d0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
207e0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
207f0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
20800 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
20810 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
20820 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
20830 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
20840 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
20850 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
20860 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
20870 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
20880 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
20890 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
208a0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
208b0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
208c0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
208d0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
208e0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
208f0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
20900 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
20910 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
20920 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
20930 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
20940 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
20950 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
20960 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
20970 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
20980 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
20990 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
209a0 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
209b0 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
209c0 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
209d0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
209e0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
209f0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
20a00 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
20a10 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
20a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
20a30 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
20a40 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
20a50 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
20a60 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
20a70 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
20a80 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
20a90 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
20aa0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
20ab0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
20ac0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
20ad0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
20ae0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
20af0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
20b00 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
20b10 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
20b20 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
20b30 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
20b40 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
20b50 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
20b60 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
20b70 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
20b80 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
20b90 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
20ba0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
20bb0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
20bc0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
20bd0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
20be0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
20bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
20c00 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
20c10 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
20c20 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
20c30 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
20c40 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
20c50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20c60 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
20c70 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
20c80 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
20c90 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
20ca0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
20cb0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
20cc0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
20cd0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
20ce0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
20cf0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
20d00 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
20d10 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
20d20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20d30 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
20d40 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
20d50 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
20d60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20d70 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
20d80 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
20d90 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
20da0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
20db0 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
20dc0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
20dd0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
20de0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
20df0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
20e00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
20e10 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
20e20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
20e30 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
20e40 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
20e50 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
20e60 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
20e70 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
20e80 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
20e90 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
20ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
20eb0 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
20ec0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
20ed0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
20ee0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
20ef0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
20f00 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
20f10 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
20f20 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
20f30 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
20f40 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
20f50 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
20f60 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
20f70 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
20f80 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
20f90 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
20fa0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
20fb0 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
20fc0 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
20fd0 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
20fe0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
20ff0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21000 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
21010 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
21020 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
21030 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
21040 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
21050 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
21060 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
21070 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
21080 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
21090 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
210a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
210b0 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
210c0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
210d0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
210e0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
210f0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
21100 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21110 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
21120 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
21130 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
21140 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
21150 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
21160 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
21170 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
21180 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
21190 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
211a0 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
211b0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
211c0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
211d0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
211e0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
211f0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
21200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21210 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
21220 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
21230 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
21240 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
21250 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
21260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21270 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
21280 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
21290 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
212a0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
212b0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
212c0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
212d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
212e0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
212f0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
21300 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
21310 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21320 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
21330 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
21340 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55  ction.** CONSTRU
21350 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  CTOR: sqlite3.**
21360 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
21370 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
21380 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
21390 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
213a0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
213b0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
213c0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
213d0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
213e0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
213f0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
21400 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
21410 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
21420 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
21430 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
21440 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
21450 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
21460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21470 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
21480 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
21490 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
214a0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
214b0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
214c0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
214d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
214e0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
214f0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
21500 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
21510 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
21520 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
21530 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
21540 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
21550 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
21560 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
21570 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
21580 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
21590 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
215a0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
215b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
215c0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
215d0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
215e0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
215f0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
21600 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
21610 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
21620 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
21630 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
21640 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
21650 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
21660 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
21670 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
21680 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
21690 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
216a0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
216b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
216c0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
216d0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f  will be UTF-8 fo
216e0 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61  r databases crea
216f0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c  ted using.** sql
21700 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
21710 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21720 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
21730 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74  encoding for dat
21740 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65  abases.** create
21750 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
21760 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65  open16() will be
21770 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
21780 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
21790 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
217a0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
217b0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
217c0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
217d0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
217e0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
217f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21800 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
21810 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
21820 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
21830 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
21840 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
21850 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
21860 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21870 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
21880 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
21890 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
218a0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
218b0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
218c0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
218d0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
218e0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
218f0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
21900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
21910 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
21920 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
21930 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
21940 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
21950 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
21960 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
21970 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
21980 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
21990 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
219a0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
219b0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
219c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
219d0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
219e0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
219f0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
21a00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
21a10 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
21a20 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
21a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21a40 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
21a50 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
21a60 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
21a70 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
21a80 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
21a90 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
21aa0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
21ab0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
21ac0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
21ad0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
21ae0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
21af0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
21b00 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21b10 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
21b20 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
21b30 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
21b40 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
21b50 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
21b60 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
21b70 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
21b80 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
21b90 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
21ba0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
21bb0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
21bc0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
21bd0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
21be0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
21bf0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
21c00 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
21c10 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
21c20 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21c30 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
21c40 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
21c50 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
21c60 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
21c70 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
21c80 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
21c90 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
21ca0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
21cb0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
21cc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21cd0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
21ce0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
21cf0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
21d00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21d10 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
21d20 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
21d30 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
21d40 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
21d50 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
21d60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21d70 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
21d80 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
21d90 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
21da0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
21db0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21dc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
21dd0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
21de0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
21df0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
21e00 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
21e10 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
21e20 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
21e30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
21e40 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
21e50 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
21e60 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
21e70 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
21e80 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
21e90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
21ea0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
21eb0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
21ec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21ed0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
21ee0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
21ef0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
21f00 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
21f10 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
21f20 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
21f30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
21f40 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
21f50 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21f60 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
21f70 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
21f80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21f90 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
21fa0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
21fb0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
21fc0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
21fd0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
21fe0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
21ff0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
22000 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
22010 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
22020 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
22030 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22040 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
22050 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22060 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
22070 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
22080 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
22090 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
220a0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
220b0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
220c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
220d0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
220e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
220f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
22100 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
22110 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
22120 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
22130 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
22140 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
22150 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
22160 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
22170 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
22180 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
22190 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
221a0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
221b0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
221c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
221d0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
221e0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
221f0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
22200 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
22210 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
22220 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
22230 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
22240 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
22250 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
22260 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
22270 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
22280 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
22290 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
222a0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
222b0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
222c0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
222d0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
222e0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
222f0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
22300 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
22310 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
22320 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
22330 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
22340 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
22350 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
22360 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
22370 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
22380 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
22390 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
223a0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
223b0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
223c0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
223d0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
223e0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
223f0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
22400 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
22410 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
22420 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
22430 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
22440 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
22450 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
22460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
22470 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
22480 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
22490 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
224a0 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
224b0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
224c0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
224d0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
224e0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
224f0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
22500 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
22510 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
22520 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
22530 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
22540 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
22550 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
22560 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
22570 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
22580 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
22590 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
225a0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
225b0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
225c0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
225d0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
225e0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
225f0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
22600 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
22610 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
22620 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
22630 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
22640 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
22650 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
22660 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
22670 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
22680 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
22690 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
226a0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
226b0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
226c0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
226d0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
226e0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
226f0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
22700 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
22710 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
22720 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
22730 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
22740 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
22750 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
22760 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
22770 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
22780 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
22790 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
227a0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
227b0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
227c0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
227d0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
227e0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
227f0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
22800 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
22810 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
22820 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
22830 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
22840 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
22850 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
22860 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
22870 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
22880 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
22890 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
228a0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
228b0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
228c0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
228d0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
228e0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
228f0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
22900 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
22910 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
22920 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
22930 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
22940 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
22950 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
22960 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
22970 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
22980 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
22990 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
229a0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
229b0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
229c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
229d0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
229e0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
229f0 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
22a00 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
22a10 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
22a20 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
22a30 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
22a40 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
22a50 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
22a60 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
22a70 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
22a80 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
22a90 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
22aa0 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
22ab0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
22ac0 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
22ad0 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
22ae0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
22af0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
22b00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
22b10 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
22b20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
22b30 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
22b40 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
22b50 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
22b60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
22b70 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
22b80 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
22b90 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
22ba0 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
22bb0 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
22bc0 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
22bd0 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
22be0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
22bf0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
22c00 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
22c10 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
22c20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22c30 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
22c40 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
22c50 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
22c60 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
22c70 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
22c80 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
22c90 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
22ca0 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
22cb0 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
22cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22cd0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
22ce0 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
22cf0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
22d00 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
22d10 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
22d20 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
22d30 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
22d40 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
22d50 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
22d60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
22d70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22d80 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
22d90 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
22da0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
22db0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
22dc0 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
22dd0 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
22de0 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
22df0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
22e00 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
22e10 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
22e20 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
22e30 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
22e40 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
22e50 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
22e60 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
22e70 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
22e80 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
22e90 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
22ea0 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
22eb0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
22ec0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
22ed0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
22ee0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
22ef0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
22f00 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
22f10 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
22f20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
22f30 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
22f40 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
22f50 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
22f60 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
22f70 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
22f80 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
22f90 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
22fa0 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
22fb0 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
22fc0 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
22fd0 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
22fe0 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
22ff0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
23000 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
23010 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
23020 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
23030 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
23040 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
23050 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
23060 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
23070 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
23080 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
23090 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
230a0 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
230b0 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
230c0 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
230d0 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
230e0 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
230f0 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
23100 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
23110 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
23120 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
23130 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
23140 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23150 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
23160 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
23170 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
23180 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
23190 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
231a0 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
231b0 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
231c0 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
231d0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
231e0 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
231f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
23200 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
23210 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
23220 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
23230 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
23240 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
23250 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
23260 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
23270 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
23280 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
23290 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
232a0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
232b0 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
232c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
232d0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
232e0 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
232f0 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
23300 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
23310 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
23320 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
23330 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
23340 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
23350 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
23360 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
23370 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
23380 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
23390 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
233a0 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
233b0 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
233c0 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
233d0 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
233e0 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
233f0 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
23400 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
23410 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
23420 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
23430 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
23440 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
23450 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
23460 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
23470 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
23480 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
23490 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
234a0 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
234b0 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
234c0 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
234d0 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
234e0 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
234f0 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
23500 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
23510 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
23520 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
23530 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
23540 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
23550 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
23560 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
23570 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
23580 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
23590 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
235a0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
235b0 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
235c0 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
235d0 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
235e0 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
235f0 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
23600 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
23610 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
23620 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
23630 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
23640 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
23650 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
23660 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
23670 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
23680 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
23690 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
236a0 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
236b0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
236c0 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
236d0 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
236e0 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
236f0 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
23700 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
23710 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
23720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
23730 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
23740 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
23750 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
23760 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
23770 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
23780 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
23790 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
237a0 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
237b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
237c0 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
237d0 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
237e0 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
237f0 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
23800 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
23810 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
23820 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
23830 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
23840 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
23850 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
23860 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
23870 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
23880 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
23890 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
238a0 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
238b0 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
238c0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
238d0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
238e0 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
238f0 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
23900 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
23910 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
23920 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
23930 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
23940 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
23950 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
23960 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
23970 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
23980 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
23990 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
239a0 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
239b0 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
239c0 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
239d0 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
239e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
239f0 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
23a00 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
23a10 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
23a20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
23a30 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
23a40 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
23a50 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
23a60 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
23a70 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
23a80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
23a90 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
23aa0 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
23ab0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
23ac0 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
23ad0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
23ae0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23af0 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
23b00 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
23b10 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
23b20 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23b30 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
23b40 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
23b50 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
23b60 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
23b70 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
23b80 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
23b90 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
23ba0 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
23bb0 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
23bc0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
23bd0 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
23be0 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
23bf0 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
23c00 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
23c10 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
23c20 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
23c30 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
23c40 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
23c50 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
23c60 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
23c70 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
23c80 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
23c90 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
23ca0 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
23cb0 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
23cc0 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
23cd0 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
23ce0 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
23cf0 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
23d00 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
23d10 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
23d20 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
23d30 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
23d40 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
23d50 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
23d60 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
23d70 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
23d80 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
23d90 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
23da0 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
23db0 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
23dc0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
23dd0 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
23de0 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
23df0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23e00 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23e10 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
23e20 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
23e30 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
23e40 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23e50 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
23e60 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
23e70 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
23e80 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
23e90 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
23ea0 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
23eb0 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
23ec0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
23ed0 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
23ee0 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
23ef0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
23f00 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
23f10 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
23f20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
23f30 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
23f40 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
23f50 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
23f60 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
23f70 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
23f80 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
23f90 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
23fa0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
23fb0 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
23fc0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
23fd0 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
23fe0 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
23ff0 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
24000 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
24010 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
24020 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
24030 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
24040 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
24050 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
24060 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
24070 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
24080 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
24090 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
240a0 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
240b0 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
240c0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
240d0 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
240e0 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
240f0 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
24100 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
24110 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
24120 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
24130 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
24140 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
24150 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
24160 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
24170 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
24180 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
24190 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
241a0 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
241b0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
241c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
241d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
241e0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
241f0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
24200 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
24210 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
24220 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
24230 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
24240 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
24250 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
24260 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
24270 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
24280 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
24290 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
242a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
242b0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
242c0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
242d0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
242e0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
242f0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
24300 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
24310 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
24320 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
24330 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
24340 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
24350 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
24360 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
24370 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
24380 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
24390 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
243a0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
243b0 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tory].*/.int sql
243c0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
243d0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
243e0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
243f0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
24400 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
24410 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
24420 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
24430 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
24440 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
24450 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
24460 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24470 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24480 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
24490 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
244a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
244b0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
244c0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
244d0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
244e0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
244f0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
24500 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
24510 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
24520 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
24530 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
24540 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
24550 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
24560 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
24570 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
24580 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
24590 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
245a0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
245b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
245c0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
245d0 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
245e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
245f0 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
24600 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
24610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
24620 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
24630 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
24640 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
24650 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
24660 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
24670 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
24680 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
24690 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
246a0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
246b0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
246c0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
246d0 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
246e0 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
246f0 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
24700 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
24710 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
24720 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
24730 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
24740 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
24750 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
24760 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
24770 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
24780 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
24790 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
247a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
247b0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
247c0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
247d0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
247e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
247f0 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
24800 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
24810 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
24820 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
24830 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
24840 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
24850 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
24860 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
24870 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
24880 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
24890 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
248a0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
248b0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
248c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
248d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
248e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
248f0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24900 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
24910 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
24920 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
24930 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
24940 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
24950 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
24960 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
24970 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
24980 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24990 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
249a0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
249b0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
249c0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
249d0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
249e0 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
249f0 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
24a00 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
24a10 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
24a20 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
24a30 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
24a40 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24a50 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
24a60 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
24a70 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
24a80 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
24a90 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
24aa0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
24ab0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
24ac0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
24ad0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
24ae0 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
24af0 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
24b00 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
24b10 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
24b20 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
24b30 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
24b40 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
24b50 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
24b60 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24b70 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
24b80 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
24b90 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
24ba0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
24bb0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
24bc0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
24bd0 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
24be0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
24bf0 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
24c00 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
24c10 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
24c20 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
24c30 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
24c40 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
24c50 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
24c60 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
24c70 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
24c80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
24c90 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
24ca0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
24cb0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
24cc0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
24cd0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24ce0 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
24cf0 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
24d00 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
24d10 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
24d20 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
24d30 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
24d40 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
24d50 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
24d60 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
24d70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
24d80 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
24d90 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
24da0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
24db0 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
24dc0 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
24dd0 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
24de0 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
24df0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
24e00 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  am);.int sqlite3
24e10 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
24e20 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
24e30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
24e40 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
24e50 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
24e60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
24e70 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
24e80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
24e90 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
24ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
24eb0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
24ec0 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
24ed0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
24ee0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
24ef0 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
24f00 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
24f10 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
24f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24f30 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
24f40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
24f50 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
24f60 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
24f70 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
24f80 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
24f90 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24fa0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
24fb0 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
24fc0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
24fd0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
24fe0 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
24ff0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
25000 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
25010 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
25020 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
25030 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25040 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
25050 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
25060 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
25070 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
25080 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
25090 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
250a0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
250b0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
250c0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
250d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
250e0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
250f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
25100 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
25110 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
25120 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
25130 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
25140 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
25150 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
25160 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
25170 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
25180 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
25190 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
251a0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
251b0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
251c0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
251d0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
251e0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
251f0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
25200 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
25210 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
25220 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
25230 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
25240 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
25250 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
25260 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
25270 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
25280 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
25290 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
252a0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
252b0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
252c0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
252d0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
252e0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
252f0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
25300 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
25310 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
25320 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
25330 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
25340 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
25350 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
25360 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
25370 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
25380 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
25390 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
253a0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
253b0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
253c0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
253d0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
253e0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
253f0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
25400 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
25410 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
25420 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
25430 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
25440 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
25450 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
25460 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
25470 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
25480 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
25490 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
254a0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
254b0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
254c0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
254d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
254e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
254f0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
25500 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
25510 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
25520 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
25530 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
25540 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
25550 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
25560 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
25570 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
25580 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
25590 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
255a0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
255b0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
255c0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
255d0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
255e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
255f0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
25600 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
25610 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
25620 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
25630 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
25640 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
25650 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
25660 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
25670 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
25680 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
25690 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
256a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
256b0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
256c0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
256d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
256e0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
256f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25700 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
25710 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
25720 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
25730 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
25740 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
25750 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
25760 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
25770 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
25780 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
25790 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
257a0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
257b0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
257c0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
257d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
257e0 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e  that.** has been
257f0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62   compiled into b
25800 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69  inary form and i
25810 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76  s ready to be ev
25820 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  aluated..**.** T
25830 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c  hink of each SQL
25840 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20   statement as a 
25850 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65  separate compute
25860 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a  r program.  The.
25870 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
25880 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63  text is source c
25890 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64  ode.  A prepared
258a0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
258b0 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d  t .** is the com
258c0 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64  piled object cod
258d0 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74  e.  All SQL must
258e0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   be converted in
258f0 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64  to a.** prepared
25900 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72   statement befor
25910 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e  e it can be run.
25920 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d  .**.** The life-
25930 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61  cycle of a prepa
25940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
25950 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65  ject usually goe
25960 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  s like this:.**.
25970 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
25980 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61  Create the prepa
25990 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
259a0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
259b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
259c0 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  ]..** <li> Bind 
259d0 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d  values to [param
259e0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
259f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25a00 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
25a10 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
25a20 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
25a30 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
25a40 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
25a50 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
25a60 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61   Reset the prepa
25a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
25a80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
25a90 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
25aa0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
25ab0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
25ac0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
25ad0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
25ae0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
25af0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
25b00 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
25b10 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  l>.*/.typedef st
25b20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
25b30 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
25b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b50 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
25b60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
25b70 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  te3.**.** ^(This
25b80 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
25b90 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
25ba0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
25bb0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
25bc0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
25bd0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
25be0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
25bf0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25c00 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
25c10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
25c20 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
25c30 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
25c40 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
25c50 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
25c60 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
25c70 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
25c80 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
25c90 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
25ca0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
25cb0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
25cc0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
25cd0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
25ce0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
25cf0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
25d00 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
25d10 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
25d20 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
25d30 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
25d40 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
25d50 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
25d60 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
25d70 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
25d80 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
25d90 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
25da0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25db0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
25dc0 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
25dd0 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
25de0 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
25df0 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
25e00 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
25e10 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
25e20 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
25e30 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
25e40 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
25e50 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
25e60 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
25e70 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
25e80 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
25e90 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
25ea0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
25eb0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
25ec0 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
25ed0 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
25ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
25ef0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
25f00 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
25f10 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
25f20 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
25f30 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
25f40 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
25f50 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
25f60 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
25f70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
25f80 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
25f90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25fa0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
25fb0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
25fc0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
25fd0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
25fe0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
25ff0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
26000 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
26010 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
26020 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
26030 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
26040 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
26050 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
26060 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
26070 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
26080 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
26090 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
260a0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
260b0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
260c0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
260d0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
260e0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
260f0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
26100 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
26110 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
26120 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
26130 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
26140 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
26150 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
26160 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
26170 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
26180 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
26190 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
261a0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
261b0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
261c0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
261d0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
261e0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
261f0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
26200 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
26210 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
26220 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
26230 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
26240 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
26250 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
26260 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
26270 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
26280 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
26290 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
262a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
262b0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
262c0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
262d0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
262e0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
262f0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
26300 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
26310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
26320 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
26330 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
26340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26350 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
26360 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
26370 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
26380 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
26390 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
263a0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
263b0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
263c0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
263d0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
263e0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
263f0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
26400 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
26410 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
26420 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
26430 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
26440 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
26450 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
26460 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
26470 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
26480 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
26490 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
264a0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
264b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
264c0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
264d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
264e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
264f0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
26500 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
26510 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
26520 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
26530 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26540 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
26550 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26560 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
26570 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26580 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
26590 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
265a0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
265b0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
265c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
265d0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
265e0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
265f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26600 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26610 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
26620 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
26630 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
26640 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
26650 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
26660 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
26670 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
26680 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
26690 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
266a0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
266b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
266c0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
266d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
266e0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
266f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26700 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
26710 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
26720 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
26730 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
26740 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26750 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
26760 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26770 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26780 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
26790 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
267a0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
267b0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
267c0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
267d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
267e0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
267f0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26800 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
26810 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26820 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26830 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
26840 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
26850 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
26860 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
26870 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
26880 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
26890 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
268a0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
268b0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
268c0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
268d0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
268e0 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
268f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26900 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26910 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
26920 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
26930 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
26940 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
26950 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
26960 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
26970 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26980 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
26990 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
269a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
269b0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
269c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
269d0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
269e0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
269f0 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
26a00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26a10 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
26a20 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
26a30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
26a40 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
26a50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26a60 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
26a70 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
26a80 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
26a90 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
26aa0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
26ab0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26ac0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
26ad0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
26ae0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26af0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
26b00 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
26b10 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
26b20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
26b30 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
26b40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
26b50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26b60 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
26b70 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
26b80 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
26b90 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
26ba0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
26bb0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
26bc0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
26bd0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26be0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
26bf0 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
26c00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26c10 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
26c20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26c30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26c40 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
26c50 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
26c60 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
26c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26c80 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
26c90 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
26ca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26cb0 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
26cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
26cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26ce0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
26cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
26d00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26d10 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
26d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
26d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26d40 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
26d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26d60 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
26d70 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
26d80 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
26d90 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
26da0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
26db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26dc0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
26dd0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
26de0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
26df0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
26e00 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
26e10 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
26e20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
26e30 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26e40 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
26e50 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
26e60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26e70 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
26e80 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
26e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26ea0 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
26eb0 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
26ec0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
26ed0 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
26ee0 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
26ef0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
26f00 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
26f10 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
26f20 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
26f30 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d  t compiler}.** M
26f40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
26f50 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
26f60 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
26f70 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
26f80 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
26f90 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
26fa0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
26fb0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
26fc0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
26fd0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
26fe0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
26ff0 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
27000 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
27010 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
27020 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
27030 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
27040 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
27050 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
27060 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
27070 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
27080 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
27090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
270a0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
270b0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
270c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
270d0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
270e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
270f0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
27100 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
27110 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
27120 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
27130 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
27140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27150 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
27160 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
27170 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27180 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
27190 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
271a0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
271b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
271c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65  e argument is ne
271d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71  gative, then zSq
271e0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
271f0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
27200 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
27210 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74  f nByte is posit
27220 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
27230 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
27240 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
27250 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74   zSql.  ^If nByt
27260 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  e is zero, then 
27270 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  no prepared.** s
27280 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65  tatement is gene
27290 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  rated..** If the
272a0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68   caller knows th
272b0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
272c0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
272d0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a  rminated, then.*
272e0 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  * there is a sma
272f0 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ll performance a
27300 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73  dvantage to pass
27310 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
27320 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
27330 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
27340 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
27350 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
27360 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
27370 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
27380 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
27390 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
273a0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
273b0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
273c0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
273d0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
273e0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
273f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
27400 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
27410 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
27420 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
27430 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
27440 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
27450 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
27460 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
27470 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
27480 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
27490 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
274a0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
274b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
274c0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
274d0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
274e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
274f0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
27500 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
27510 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
27520 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
27530 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
27540 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
27550 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
27560 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
27570 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
27580 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
27590 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
275a0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
275b0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
275c0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
275d0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
275e0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
275f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27600 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
27610 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
27620 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
27630 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
27640 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
27650 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
27660 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
27670 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
27680 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
27690 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
276a0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
276b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
276c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
276d0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
276e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
276f0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
27700 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
27710 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
27720 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
27730 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
27740 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
27750 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
27760 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
27770 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
27780 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
27790 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
277a0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
277b0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
277c0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
277d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
277e0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
277f0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
27800 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
27810 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
27820 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
27830 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
27840 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
27850 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
27860 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
27870 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
27880 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
27890 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
278a0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
278b0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
278c0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
278d0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
278e0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
278f0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
27900 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
27910 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
27920 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
27930 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
27940 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
27950 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
27960 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
27970 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
27980 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
27990 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
279a0 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
279b0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
279c0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
279d0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
279e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
279f0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
27a00 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
27a10 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
27a20 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
27a30 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
27a40 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
27a50 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
27a60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
27a70 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
27a80 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
27a90 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
27aa0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
27ab0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
27ac0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
27ad0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
27ae0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27af0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
27b00 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
27b10 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
27b20 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
27b30 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
27b40 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
27b50 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
27b60 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
27b70 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
27b80 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
27b90 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
27ba0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
27bb0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
27bc0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
27bd0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
27be0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
27bf0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
27c00 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
27c10 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
27c20 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
27c30 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
27c40 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
27c50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
27c60 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
27c70 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
27c80 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
27c90 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
27ca0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
27cb0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
27cc0 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
27cd0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
27ce0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
27cf0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
27d00 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
27d10 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
27d20 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
27d30 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
27d40 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
27d50 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
27d60 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
27d70 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
27d80 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
27d90 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
27da0 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
27db0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
27dc0 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
27dd0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
27de0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
27df0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
27e00 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
27e10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
27e20 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
27e30 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
27e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
27e50 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
27e60 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
27e70 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
27e80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
27e90 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
27ea0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
27eb0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
27ec0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27ed0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27ee0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27ef0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27f00 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27f10 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27f20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27f30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27f40 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
27f50 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27f60 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
27f70 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
27f80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
27f90 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
27fa0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27fb0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27fc0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27fd0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
27fe0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27ff0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
28000 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28010 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28020 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28030 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28040 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28050 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28060 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28070 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28080 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
28090 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
280a0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
280b0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
280c0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
280d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
280e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
280f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
28100 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
28110 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
28120 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
28130 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
28140 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
28150 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
28160 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
28170 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
28180 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
28190 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
281a0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
281b0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
281c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
281d0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
281e0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
281f0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
28200 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
28210 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
28220 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
28230 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
28240 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
28250 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28260 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
28270 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
28280 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
28290 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
282a0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
282b0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
282c0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
282d0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
282e0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
282f0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
28300 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
28310 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
28320 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28330 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28340 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28350 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
28360 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
28370 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
28380 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
28390 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
283a0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
283b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
283c0 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
283d0 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
283e0 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
283f0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
28400 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28410 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
28420 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
28430 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
28440 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
28450 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
28460 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28470 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
28480 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28490 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
284a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
284b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
284c0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
284d0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
284e0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
284f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
28500 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
28510 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28520 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
28530 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
28540 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
28550 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
28560 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28570 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
28580 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
28590 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
285a0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
285b0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
285c0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
285d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
285e0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
285f0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
28600 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
28610 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
28620 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
28630 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
28640 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
28650 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
28660 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
28670 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
28680 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
28690 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
286a0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
286b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
286c0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
286d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
286e0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
286f0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
28700 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
28710 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
28720 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
28730 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
28740 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
28750 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
28760 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
28770 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
28780 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
28790 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
287a0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
287b0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
287c0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
287d0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
287e0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
287f0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
28800 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
28810 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
28820 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
28830 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
28840 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
28850 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28860 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
28870 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
28880 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
28890 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
288a0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
288b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
288c0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
288d0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
288e0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
288f0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
28900 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
28910 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
28920 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
28930 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
28940 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
28950 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
28960 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
28970 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
28980 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
28990 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
289a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
289b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
289c0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
289d0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
289e0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
289f0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
28a00 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
28a10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28a20 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
28a30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
28a40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28a50 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
28a60 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
28a70 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
28a80 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Reset.** METHOD:
28a90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
28aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28ab0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
28ac0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28ad0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
28ae0 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
28af0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
28b00 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
28b10 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
28b20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
28b30 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
28b40 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
28b50 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
28b60 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
28b70 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
28b80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
28b90 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
28ba0 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
28bb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28bc0 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
28bd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
28be0 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
28bf0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
28c00 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
28c10 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
28c20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c30 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
28c40 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
28c50 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
28c60 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
28c70 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
28c80 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
28c90 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
28ca0 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
28cb0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
28cc0 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
28cd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28ce0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
28cf0 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
28d00 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
28d10 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
28d20 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
28d30 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
28d40 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
28d50 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
28d60 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
28d70 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
28d80 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
28d90 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
28da0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
28db0 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
28dc0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
28dd0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
28de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
28df0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
28e00 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
28e10 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
28e20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28e30 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
28e40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
28e50 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
28e60 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
28e70 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
28e80 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
28e90 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
28ea0 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
28eb0 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
28ec0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
28ed0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
28ee0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
28ef0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
28f00 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
28f10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
28f20 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
28f30 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
28f40 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
28f50 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
28f60 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
28f70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28f80 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
28f90 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
28fa0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
28fb0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
28fc0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
28fd0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28fe0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
28ff0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
29000 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
29010 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
29020 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29030 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
29040 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
29050 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
29060 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
29070 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
29080 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
29090 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
290a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
290b0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
290c0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
290d0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
290e0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
290f0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
29100 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
29110 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
29120 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
29130 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29140 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
29150 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
29160 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
29170 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29180 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
29190 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
291a0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
291b0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
291c0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
291d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
291e0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
291f0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
29200 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
29210 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
29220 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
29230 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
29240 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
29250 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
29260 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
29270 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
29280 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
29290 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
292a0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
292b0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
292c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
292d0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
292e0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
292f0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
29300 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
29310 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
29320 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
29330 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
29340 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
29350 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
29360 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
29370 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
29380 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
29390 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
293a0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
293b0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
293c0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
293d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
293e0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
293f0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
29400 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
29410 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
29420 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
29430 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29440 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
29450 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
29460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29470 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
29480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
29490 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
294a0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
294b0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
294c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
294d0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
294e0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
294f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
29500 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29510 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
29520 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
29530 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
29540 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
29550 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
29560 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
29570 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
29580 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29590 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
295a0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
295b0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
295c0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
295d0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
295e0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
295f0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
29600 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
29610 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
29620 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
29630 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
29640 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
29650 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
29660 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
29670 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
29680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
29690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
296a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
296b0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
296c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
296d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
296e0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
296f0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
29700 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
29710 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
29720 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
29730 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
29740 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
29750 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29760 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
29770 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
29780 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
29790 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
297a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
297b0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
297c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
297d0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
297e0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
297f0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
29800 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
29810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
29820 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
29830 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
29840 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
29850 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
29860 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
29870 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
29880 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
29890 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
298a0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
298b0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
298c0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d  er binding}.** M
298d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
298e0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  tmt.**.** ^(In t
298f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
29900 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
29910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29920 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
29930 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
29940 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
29950 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
29960 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
29970 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
29980 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
29990 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
299a0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
299b0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
299c0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
299d0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
299e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
299f0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
29a00 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
29a10 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
29a20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
29a30 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
29a40 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
29a50 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
29a60 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
29a70 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
29a80 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
29a90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
29aa0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
29ab0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
29ac0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
29ad0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29ae0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
29af0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
29b00 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
29b10 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
29b20 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29b30 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
29b40 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
29b50 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
29b60 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
29b70 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
29b80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29b90 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
29ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
29bb0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
29bc0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
29bd0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
29be0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
29bf0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
29c00 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
29c10 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
29c20 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
29c30 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
29c40 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
29c50 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
29c60 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
29c70 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
29c80 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
29c90 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
29ca0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
29cb0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
29cc0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
29cd0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
29ce0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
29cf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29d00 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
29d10 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
29d20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
29d30 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
29d40 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
29d50 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
29d60 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
29d70 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
29d80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
29d90 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
29da0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
29db0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29dc0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
29dd0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
29de0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
29df0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
29e00 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
29e10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
29e20 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
29e30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
29e40 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
29e50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29e60 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
29e70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
29e80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29e90 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
29ea0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
29eb0 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
29ec0 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
29ed0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
29ee0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
29ef0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
29f00 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
29f10 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
29f20 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
29f30 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
29f40 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
29f50 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
29f60 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
29f70 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
29f80 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
29f90 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
29fa0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
29fb0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
29fc0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
29fd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
29fe0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29ff0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2a000 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2a010 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2a020 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2a030 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2a040 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2a050 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2a060 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2a070 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2a080 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a090 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2a0a0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2a0b0 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2a0c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2a0d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2a0e0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2a0f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a100 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2a110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a120 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2a130 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2a140 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2a150 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
2a160 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2a170 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
2a180 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
2a190 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
2a1a0 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
2a1b0 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
2a1c0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
2a1d0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
2a1e0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
2a1f0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
2a200 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
2a210 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
2a220 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2a230 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
2a240 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
2a250 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
2a260 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
2a270 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
2a280 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
2a290 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
2a2a0 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
2a2b0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
2a2c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2a2d0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2a2e0 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
2a2f0 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
2a300 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
2a310 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2a320 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2a330 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2a340 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2a350 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2a360 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2a370 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2a380 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2a390 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2a3a0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2a3b0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
2a3c0 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
2a3d0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2a3e0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2a3f0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2a400 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2a410 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2a420 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2a430 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2a440 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2a450 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2a460 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2a470 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2a480 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2a490 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2a4a0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2a4b0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2a4c0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2a4d0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2a4e0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2a4f0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2a500 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2a510 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2a520 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2a530 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
2a540 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2a550 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
2a560 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
2a570 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2a580 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
2a590 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2a5a0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2a5b0 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
2a5c0 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
2a5d0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
2a5e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2a5f0 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
2a600 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2a610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a620 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
2a630 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
2a640 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
2a650 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
2a660 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
2a670 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
2a680 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
2a690 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2a6a0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
2a6b0 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
2a6c0 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
2a6d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2a6e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2a6f0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2a700 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2a710 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2a720 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2a730 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2a740 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2a750 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2a760 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2a770 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2a780 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2a790 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2a7a0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2a7b0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2a7c0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2a7d0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2a7e0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2a7f0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2a800 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2a810 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2a820 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2a830 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2a840 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2a850 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2a860 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2a870 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2a880 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2a890 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2a8a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2a8b0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2a8c0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2a8d0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2a8e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a8f0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2a900 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a910 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2a920 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a930 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2a940 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2a950 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2a960 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2a970 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2a980 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2a990 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2a9a0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2a9b0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2a9c0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2a9d0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2a9e0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2a9f0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2aa00 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2aa10 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2aa20 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2aa30 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2aa40 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2aa50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2aa60 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2aa70 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2aa80 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2aa90 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2aaa0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2aab0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2aac0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2aad0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2aae0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2aaf0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2ab00 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2ab10 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2ab20 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2ab30 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2ab40 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2ab50 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2ab60 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2ab70 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2ab80 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2ab90 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2aba0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2abb0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2abc0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2abd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2abe0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2abf0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2ac00 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2ac10 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2ac20 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2ac30 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2ac40 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2ac50 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2ac60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ac70 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2ac80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ac90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2aca0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2acb0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2acc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2acd0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2ace0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2acf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2ad00 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2ad10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2ad20 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2ad30 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2ad40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ad50 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2ad60 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2ad70 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2ad80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2ad90 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
2ada0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2adb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2adc0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2add0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2ade0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2adf0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2ae00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2ae10 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2ae20 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
2ae30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2ae40 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2ae50 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
2ae60 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  *,int,void(*)(vo
2ae70 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2ae80 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2ae90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2aea0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2aeb0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2aec0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2aed0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2aee0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2aef0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2af00 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2af10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2af20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2af30 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
2af40 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
2af50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2af60 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2af70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2af80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2af90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2afa0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2afb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2afc0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2afd0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2afe0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2aff0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
2b000 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b010 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2b020 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2b030 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2b040 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2b050 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2b060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2b070 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2b080 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2b090 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2b0a0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2b0b0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2b0c0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2b0d0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2b0e0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2b0f0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2b100 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2b110 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2b120 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2b130 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2b140 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2b150 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2b160 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2b170 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2b180 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2b190 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2b1a0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2b1b0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2b1c0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2b1d0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2b1e0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2b1f0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2b200 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2b210 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2b220 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2b230 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2b240 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2b250 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2b260 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2b270 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b280 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2b290 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b2a0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b2b0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b2c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b2d0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2b2e0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2b2f0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2b300 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2b310 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
2b320 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2b330 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2b340 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2b350 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2b360 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2b370 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2b380 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2b390 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2b3a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2b3b0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2b3c0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2b3d0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2b3e0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2b3f0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2b400 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2b410 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2b420 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2b430 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2b440 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2b450 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2b460 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2b470 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2b480 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2b490 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2b4a0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2b4b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2b4c0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2b4d0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2b4e0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2b4f0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2b500 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2b510 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2b520 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2b530 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2b540 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2b550 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2b560 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2b570 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2b580 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2b590 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2b5a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2b5b0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2b5c0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2b5d0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2b5e0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2b5f0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2b600 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2b610 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2b620 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2b630 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2b640 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2b650 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2b660 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2b670 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b680 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2b690 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2b6a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2b6b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2b6c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b6d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2b6e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b6f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b700 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2b710 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2b720 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2b730 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b740 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b750 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2b760 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2b770 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
2b780 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b790 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2b7a0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2b7b0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2b7c0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2b7d0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2b7e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2b7f0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2b800 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2b810 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2b820 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b830 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2b840 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2b850 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2b860 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2b870 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2b880 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2b890 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2b8a0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2b8b0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2b8c0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2b8d0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2b8e0 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2b8f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2b900 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2b910 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2b920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b930 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2b940 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2b950 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2b960 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2b970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b980 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2b990 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b9a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2b9b0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
2b9c0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
2b9d0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
2b9e0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2b9f0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
2ba00 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2ba10 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2ba20 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ba30 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2ba40 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2ba50 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2ba60 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2ba70 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2ba80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ba90 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2baa0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2bab0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2bac0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2bad0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2bae0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2baf0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
2bb00 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2bb10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2bb20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bb30 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2bb40 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2bb50 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2bb60 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2bb70 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2bb80 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2bb90 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2bba0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2bbb0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2bbc0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2bbd0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2bbe0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2bbf0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2bc00 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2bc10 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2bc20 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2bc30 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2bc40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2bc50 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2bc60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2bc70 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2bc80 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2bc90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bca0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2bcb0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2bcc0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2bcd0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2bce0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2bcf0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2bd00 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2bd10 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2bd20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2bd30 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2bd40 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2bd50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bd60 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2bd70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2bd80 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2bd90 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2bda0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2bdb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2bdc0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2bdd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2bde0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2bdf0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2be00 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2be10 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2be20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2be30 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2be40 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2be50 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2be60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2be70 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2be80 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2be90 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2bea0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2beb0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2bec0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2bed0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2bee0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2bef0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bf00 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2bf10 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2bf20 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2bf30 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2bf40 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2bf50 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2bf60 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2bf70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2bf80 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2bf90 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2bfa0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2bfb0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2bfc0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2bfd0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2bfe0 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2bff0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2c000 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2c010 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2c020 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2c030 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2c040 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2c050 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2c060 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2c070 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2c080 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2c090 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2c0a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2c0b0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2c0c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2c0d0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2c0e0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2c0f0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2c100 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2c110 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2c120 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2c130 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2c140 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2c150 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2c160 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2c170 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2c180 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2c190 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
2c1a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2c1b0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2c1c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2c1d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2c1e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c1f0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2c200 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2c210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2c220 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2c230 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2c240 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c250 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2c260 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2c270 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2c280 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2c290 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2c2a0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2c2b0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2c2c0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2c2d0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2c2e0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2c2f0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2c300 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2c310 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2c320 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2c330 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2c340 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2c350 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2c360 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2c370 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2c380 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2c390 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2c3a0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2c3b0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2c3c0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2c3d0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2c3e0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2c3f0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2c400 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2c410 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2c420 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2c430 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2c440 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2c450 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c460 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2c470 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2c480 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2c490 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2c4a0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c4c0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2c4d0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2c4e0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2c4f0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2c500 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2c510 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2c520 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2c530 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2c540 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2c550 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2c560 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2c570 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2c580 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2c590 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2c5a0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2c5b0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2c5c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c5d0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2c5e0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2c5f0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2c600 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2c610 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2c620 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2c630 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2c640 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2c650 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2c660 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2c670 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2c680 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2c690 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2c6a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2c6b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2c6c0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2c6d0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2c6e0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2c6f0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2c700 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2c710 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2c720 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2c730 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2c740 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2c750 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2c760 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2c770 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2c780 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2c790 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2c7a0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2c7b0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2c7c0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2c7d0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2c7e0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2c7f0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2c800 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2c810 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2c820 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2c830 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2c840 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2c850 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2c860 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2c870 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2c880 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2c890 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2c8a0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2c8b0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2c8c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2c8d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2c8e0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2c8f0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2c900 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2c910 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2c920 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2c930 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2c940 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2c950 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2c960 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c970 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2c980 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2c990 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2c9a0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2c9b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2c9c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2c9d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2c9e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2c9f0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2ca00 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2ca10 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2ca20 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2ca30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ca40 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2ca50 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2ca60 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2ca70 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ca80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2ca90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2caa0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2cab0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2cac0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2cad0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2cae0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2caf0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2cb00 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2cb10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2cb20 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2cb30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2cb40 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2cb50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2cb60 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2cb70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2cb80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2cb90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2cba0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2cbb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2cbc0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2cbd0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2cbe0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2cbf0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2cc00 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2cc10 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2cc20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
2cc30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2cc40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  stmt.**.** ^(The
2cc50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2cc60 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2cc70 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2cc80 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2cc90 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2cca0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2ccb0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2ccc0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2ccd0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2cce0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2ccf0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2cd00 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2cd10 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2cd20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2cd30 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2cd40 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2cd50 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2cd60 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2cd70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2cd80 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2cd90 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2cda0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2cdb0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2cdc0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2cdd0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2cde0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2cdf0 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2ce00 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2ce10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2ce20 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2ce30 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2ce40 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2ce50 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2ce60 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2ce70 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2ce80 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2ce90 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2cea0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2ceb0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2cec0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2ced0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2cee0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2cef0 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2cf00 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2cf10 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2cf20 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2cf30 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2cf40 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2cf50 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2cf60 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2cf70 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2cf80 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2cf90 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2cfa0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2cfb0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2cfc0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2cfd0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2cfe0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2cff0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2d000 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2d010 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2d020 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2d030 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2d040 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2d050 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2d060 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2d070 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2d080 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2d090 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2d0a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2d0b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2d0c0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2d0d0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2d0e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d0f0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2d100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d120 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2d130 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2d140 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2d150 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
2d160 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d170 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2d180 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2d190 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2d1a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d1b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2d1c0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2d1d0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2d1e0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2d1f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d200 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d210 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2d220 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2d230 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2d240 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2d250 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2d260 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2d270 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2d280 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2d290 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2d2a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2d2b0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2d2c0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2d2d0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2d2e0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2d2f0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2d300 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d310 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2d320 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2d330 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2d340 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2d350 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2d360 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2d370 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2d380 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2d390 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2d3a0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2d3b0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2d3c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2d3d0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2d3e0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2d3f0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2d400 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2d410 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2d420 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2d430 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2d440 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2d450 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2d460 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2d470 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2d480 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2d490 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2d4a0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2d4b0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2d4c0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2d4d0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2d4e0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2d4f0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2d500 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2d510 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2d520 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2d530 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2d540 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2d550 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2d560 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2d570 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2d580 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2d590 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2d5a0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2d5b0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2d5c0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2d5d0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2d5e0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2d5f0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2d600 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2d610 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2d620 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2d630 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2d640 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2d650 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2d660 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2d670 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2d680 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2d690 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2d6a0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2d6b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2d6c0 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2d6d0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2d6e0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2d6f0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2d700 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2d710 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2d720 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2d730 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2d740 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2d750 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2d760 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2d770 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2d780 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2d790 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2d7a0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2d7b0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2d7c0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2d7d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2d7e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2d7f0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2d800 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2d810 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2d820 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2d830 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2d840 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2d850 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2d860 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2d870 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2d880 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2d890 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2d8a0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2d8b0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2d8c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2d8d0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2d8e0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2d8f0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2d900 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2d910 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2d920 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2d930 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2d940 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2d950 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2d960 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2d970 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2d980 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2d990 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2d9a0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2d9b0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2d9c0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2d9d0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2d9e0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2d9f0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2da00 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2da10 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2da20 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2da30 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2da40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2da50 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2da60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2da70 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2da80 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2da90 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2daa0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2dab0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2dac0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2dad0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2dae0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2daf0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2db00 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2db10 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2db20 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2db30 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2db40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2db50 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2db60 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2db70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2db80 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2db90 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2dba0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2dbb0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2dbc0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2dbd0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2dbe0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2dbf0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2dc00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dc10 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2dc20 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2dc30 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2dc40 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2dc50 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2dc60 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2dc70 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2dc80 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2dc90 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2dca0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2dcb0 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2dcc0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2dcd0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2dce0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2dcf0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2dd00 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2dd10 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2dd20 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2dd30 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2dd40 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2dd50 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2dd60 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2dd70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2dd80 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2dd90 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2dda0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2ddb0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2ddc0 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2ddd0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2dde0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2ddf0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2de00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2de10 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2de20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2de30 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2de40 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2de50 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2de60 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2de70 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2de80 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2de90 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2dea0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2deb0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2dec0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2ded0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2dee0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2def0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2df00 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2df10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2df20 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2df30 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2df40 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2df50 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2df60 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2df70 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2df80 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2df90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2dfa0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2dfb0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2dfc0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2dfd0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2dfe0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2dff0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2e000 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2e010 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2e020 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2e030 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e040 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2e050 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2e060 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2e070 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2e080 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2e090 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2e0a0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2e0b0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2e0c0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2e0d0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2e0e0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2e0f0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2e100 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2e110 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2e120 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2e130 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2e140 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2e150 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e160 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2e170 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2e180 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2e190 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2e1a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2e1b0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2e1c0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2e1d0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2e1e0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2e1f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2e200 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2e210 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2e220 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2e230 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2e240 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2e250 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
2e260 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2e270 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2e280 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2e290 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2e2a0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2e2b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e2c0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2e2d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2e2e0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2e2f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2e300 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2e310 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2e320 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2e330 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2e340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2e350 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2e360 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2e370 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2e380 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2e390 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2e3a0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2e3b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2e3c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2e3d0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2e3e0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2e3f0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2e400 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2e410 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2e420 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2e430 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2e440 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2e450 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2e460 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2e470 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2e480 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2e490 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2e4a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2e4b0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2e4c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2e4d0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2e4e0 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2e4f0 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2e500 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2e510 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2e520 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2e530 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2e540 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2e550 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2e560 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2e570 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2e580 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2e590 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2e5a0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2e5b0 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2e5c0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2e5d0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2e5e0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2e5f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2e600 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2e610 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2e620 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2e630 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2e640 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2e650 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2e660 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2e670 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2e680 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2e690 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2e6a0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2e6b0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2e6c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2e6d0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2e6e0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2e6f0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2e700 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2e710 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2e720 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2e730 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2e740 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2e750 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2e760 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2e770 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2e780 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2e790 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2e7a0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2e7b0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2e7c0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2e7d0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2e7e0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2e7f0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2e800 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2e810 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2e820 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2e830 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2e840 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2e850 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2e860 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2e870 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2e880 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2e890 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2e8a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2e8b0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2e8c0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2e8d0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2e8e0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2e8f0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2e900 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2e910 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2e920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2e930 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2e940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2e950 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2e960 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2e970 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2e980 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2e990 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e9a0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
2e9b0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2e9c0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2e9d0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2e9e0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2e9f0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2ea00 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2ea10 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2ea20 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2ea30 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2ea40 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2ea50 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2ea60 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2ea70 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2ea80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ea90 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2eaa0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2eab0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2eac0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2ead0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2eae0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2eaf0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2eb00 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2eb10 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2eb20 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2eb30 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2eb40 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2eb50 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2eb60 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2eb70 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2eb80 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2eb90 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2eba0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2ebb0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2ebc0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2ebd0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2ebe0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2ebf0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2ec00 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2ec10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2ec20 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2ec30 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2ec40 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2ec50 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2ec60 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2ec70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2ec80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2ec90 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2eca0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2ecb0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2ecc0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2ecd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ece0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2ecf0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2ed00 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2ed10 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2ed20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ed30 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2ed40 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2ed50 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2ed60 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2ed70 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2ed80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ed90 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2eda0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2edb0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2edc0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2edd0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2ede0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2edf0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2ee00 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2ee10 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2ee20 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2ee30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ee40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2ee50 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2ee60 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2ee70 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2ee80 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2ee90 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2eea0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2eeb0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2eec0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2eed0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2eee0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2eef0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2ef00 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2ef10 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2ef20 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2ef30 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2ef40 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2ef50 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2ef60 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2ef70 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2ef80 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2ef90 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2efa0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2efb0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2efc0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2efd0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2efe0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2eff0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2f000 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2f010 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2f020 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2f030 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2f040 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2f050 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f060 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2f070 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2f080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2f090 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2f0a0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2f0b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2f0c0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2f0d0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2f0e0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2f0f0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2f100 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2f110 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2f120 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2f130 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2f140 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2f150 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2f160 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2f170 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f180 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2f190 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2f1a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2f1b0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2f1c0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2f1d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2f1e0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2f1f0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2f200 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2f210 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2f220 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2f230 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2f240 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2f250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f260 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2f270 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2f280 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2f290 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2f2a0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2f2b0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2f2c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f2d0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2f2e0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f2f0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2f300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f310 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2f320 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2f330 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2f340 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2f350 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2f360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f370 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2f380 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2f390 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2f3a0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2f3b0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2f3c0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2f3d0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2f3e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f3f0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2f400 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2f410 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2f420 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2f430 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2f440 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f450 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2f460 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2f470 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2f480 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2f490 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2f4a0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2f4b0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2f4c0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2f4d0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2f4e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2f4f0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2f500 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f510 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2f520 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f530 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2f540 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2f550 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2f560 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f570 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2f580 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f590 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2f5a0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2f5b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2f5c0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2f5d0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2f5e0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2f5f0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2f600 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2f610 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2f620 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2f630 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2f640 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2f650 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2f660 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2f670 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2f680 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2f690 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2f6a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f6b0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2f6c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f6d0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2f6e0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2f6f0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2f700 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2f710 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2f720 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2f730 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2f740 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2f750 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2f770 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2f780 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f790 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2f7a0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2f7b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f7c0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2f7d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f7e0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2f7f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2f800 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2f810 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2f820 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2f830 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2f840 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2f850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f860 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2f870 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2f880 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2f890 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2f8a0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2f8b0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2f8c0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2f8d0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2f8e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2f8f0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2f900 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f910 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2f920 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2f930 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2f940 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2f950 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2f960 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2f970 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2f980 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2f990 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2f9a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2f9b0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2f9c0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2f9d0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2f9e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2f9f0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2fa00 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2fa10 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2fa20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2fa30 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2fa40 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2fa50 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2fa60 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2fa70 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2fa80 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2fa90 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2faa0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2fab0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2fac0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2fad0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2fae0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2faf0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2fb00 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2fb10 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2fb20 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2fb30 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2fb40 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2fb50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2fb60 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2fb70 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2fb80 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2fb90 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2fba0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2fbb0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2fbc0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2fbd0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2fbe0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2fbf0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2fc00 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2fc10 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2fc20 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2fc30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2fc40 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2fc50 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2fc60 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2fc70 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2fc80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2fc90 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2fca0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2fcb0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2fcc0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2fcd0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2fce0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2fcf0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2fd00 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2fd10 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2fd20 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2fd30 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2fd40 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
2fd50 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
2fd60 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2fd70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2fd80 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2fd90 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2fda0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2fdb0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2fdc0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2fdd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2fde0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2fdf0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2fe00 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2fe10 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2fe20 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2fe30 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2fe40 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2fe50 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2fe60 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2fe70 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2fe80 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2fe90 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
2fea0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
2feb0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
2fec0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
2fed0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2fee0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2fef0 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2ff00 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2ff10 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2ff20 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2ff30 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2ff40 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2ff50 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2ff60 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2ff70 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2ff80 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2ff90 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2ffa0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2ffb0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2ffc0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2ffd0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2ffe0 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2fff0 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
30000 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
30010 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
30020 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
30030 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
30040 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
30050 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
30060 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
30070 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
30080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30090 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
300a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
300b0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
300c0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
300d0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
300e0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
300f0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
30100 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
30110 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
30120 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
30130 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
30140 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
30150 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
30160 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
30170 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30180 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
30190 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
301a0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
301b0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
301c0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
301d0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
301e0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
301f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
30200 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
30210 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30220 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
30230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30240 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
30250 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
30260 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
30270 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
30280 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
30290 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
302a0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
302b0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
302c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
302d0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
302e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
302f0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
30300 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
30310 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
30320 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
30330 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
30340 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
30350 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
30360 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
30370 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
30380 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
30390 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
303a0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
303b0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
303c0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
303d0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
303e0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
303f0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
30400 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
30410 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
30420 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
30430 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
30440 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
30450 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
30460 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
30470 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
30480 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
30490 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
304a0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
304b0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
304c0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
304d0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
304e0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
304f0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
30500 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
30510 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
30520 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
30530 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
30540 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
30550 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
30560 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
30570 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
30580 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30590 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
305a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
305b0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
305c0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
305d0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
305e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
305f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
30600 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
30610 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
30620 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
30630 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
30640 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
30650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30660 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
30670 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
30680 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
30690 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
306a0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
306b0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
306c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
306d0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
306e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
306f0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
30700 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
30710 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
30720 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
30730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30740 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
30750 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
30760 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
30770 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30780 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
30790 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
307a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
307b0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
307c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
307d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
307e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
307f0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
30800 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
30810 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
30820 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
30830 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
30840 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
30850 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
30860 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
30870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
30880 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
30890 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
308a0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
308b0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
308c0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
308d0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
308e0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
308f0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
30900 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
30910 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
30920 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
30930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30940 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
30950 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
30960 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
30970 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
30980 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
30990 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
309a0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
309b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
309c0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
309d0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
309e0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
309f0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
30a00 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
30a10 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
30a20 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
30a30 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
30a40 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
30a50 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
30a60 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
30a70 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
30a80 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
30a90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30aa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30ab0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30ac0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30ae0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
30af0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30b00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30b10 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
30b20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30b30 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
30b40 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
30b50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30b60 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
30b70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
30b80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30b90 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
30ba0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
30bb0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
30bc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30bd0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
30be0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
30bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30c10 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
30c20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
30c30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
30c40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30c50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
30c60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
30c70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30c80 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
30c90 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
30ca0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
30cb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30cc0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
30cd0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
30ce0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
30cf0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
30d00 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
30d10 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
30d20 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
30d30 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
30d40 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
30d50 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
30d60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
30d70 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30d80 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
30d90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
30da0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
30db0 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
30dc0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
30dd0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
30de0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
30df0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
30e00 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
30e10 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
30e20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
30e30 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
30e40 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
30e50 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
30e60 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
30e70 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
30e80 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
30e90 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
30ea0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
30eb0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
30ec0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
30ed0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
30ee0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
30ef0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
30f00 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
30f10 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
30f20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
30f30 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
30f40 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
30f50 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
30f60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
30f70 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
30f80 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
30f90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30fa0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
30fb0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
30fc0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
30fd0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
30fe0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
30ff0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
31000 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
31010 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
31020 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
31030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
31040 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
31050 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
31060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31070 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
31080 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
31090 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
310a0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
310b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
310c0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
310d0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
310e0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
310f0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
31100 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
31110 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
31120 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
31130 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
31140 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
31150 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
31160 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
31170 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
31180 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
31190 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
311a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
311b0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
311c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
311d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
311e0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
311f0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
31200 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31210 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
31220 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
31230 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
31240 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
31250 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31260 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
31270 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
31280 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
31290 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
312a0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
312b0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
312c0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
312d0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
312e0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
312f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31300 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
31310 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
31320 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
31330 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
31340 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
31350 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
31360 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
31370 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
31380 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
31390 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
313a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
313b0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
313c0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
313d0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
313e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
313f0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
31400 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
31410 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
31420 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
31430 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31440 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
31450 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
31460 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
31470 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
31480 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
31490 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
314a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
314b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
314c0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
314d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
314e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
314f0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
31500 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
31510 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
31520 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
31530 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
31540 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
31550 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
31560 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
31570 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
31580 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
31590 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
315a0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
315b0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
315c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
315d0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
315e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
315f0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
31600 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
31610 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31620 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31630 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
31640 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
31650 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
31660 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
31670 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
31680 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
31690 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
316a0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
316b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
316c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
316d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
316e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
316f0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
31700 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
31710 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
31720 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
31730 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
31740 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
31750 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
31760 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
31770 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
31780 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
31790 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
317a0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
317b0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
317c0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
317d0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
317e0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
317f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
31800 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
31810 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
31820 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
31830 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
31840 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
31850 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
31860 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
31870 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
31880 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
31890 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
318a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
318b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
318c0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
318d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
318e0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
318f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
31900 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
31910 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
31920 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
31930 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
31940 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
31950 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31960 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31970 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
31980 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
31990 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
319a0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
319b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
319c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
319d0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
319e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
319f0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
31a00 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
31a10 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
31a20 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
31a30 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
31a40 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
31a50 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
31a60 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
31a70 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
31a80 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
31a90 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
31aa0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
31ab0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
31ac0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
31ad0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
31ae0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
31af0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
31b00 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
31b10 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
31b20 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
31b30 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
31b40 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
31b50 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
31b60 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
31b70 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
31b80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31b90 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
31ba0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
31bb0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
31bc0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
31bd0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
31be0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
31bf0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
31c00 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
31c10 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
31c20 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
31c30 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
31c40 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
31c50 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
31c60 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
31c70 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
31c80 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
31c90 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
31ca0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
31cb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
31cc0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
31cd0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
31ce0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
31cf0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
31d00 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
31d10 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
31d20 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
31d30 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
31d40 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
31d50 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
31d60 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
31d70 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
31d80 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
31d90 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
31da0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
31db0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31dc0 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
31dd0 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
31de0 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
31df0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
31e00 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
31e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31e20 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
31e30 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
31e40 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
31e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31e60 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
31e70 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
31e80 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
31e90 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
31ea0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
31eb0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
31ec0 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
31ed0 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
31ee0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
31ef0 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
31f00 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
31f10 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
31f20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
31f30 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
31f40 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
31f50 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
31f60 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
31f70 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
31f80 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
31f90 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
31fa0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
31fb0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
31fc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
31fd0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
31fe0 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
31ff0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
32000 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
32010 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
32020 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
32030 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
32040 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
32050 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
32060 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
32070 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
32080 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
32090 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
320a0 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
320b0 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
320c0 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
320d0 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
320e0 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
320f0 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
32100 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
32110 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
32120 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
32130 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
32140 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
32150 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
32160 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
32170 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
32180 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
32190 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
321a0 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
321b0 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
321c0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
321d0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
321e0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
321f0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
32200 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
32210 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
32220 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
32230 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
32240 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
32250 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
32260 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
32270 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
32280 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
32290 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
322a0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
322b0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
322c0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
322d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
322e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
322f0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
32300 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
32310 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
32320 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
32330 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
32340 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
32350 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
32360 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
32370 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
32380 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
32390 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
323a0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
323b0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
323c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
323d0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
323e0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
323f0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
32400 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
32410 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
32420 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
32430 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
32440 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
32450 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
32460 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
32470 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
32480 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
32490 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
324a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
324b0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
324c0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
324d0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
324e0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
324f0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
32500 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
32510 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
32520 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
32530 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
32540 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
32550 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
32560 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
32570 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
32580 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
32590 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
325a0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
325b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
325c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
325d0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
325e0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
325f0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
32600 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
32610 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
32620 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
32630 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
32640 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
32650 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
32660 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
32670 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
32680 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
32690 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
326a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
326b0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
326c0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
326d0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
326e0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
326f0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
32700 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
32710 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
32720 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
32730 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
32740 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
32750 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
32760 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
32770 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
32780 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
32790 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
327a0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
327b0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
327c0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
327d0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
327e0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
327f0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
32800 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
32810 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
32820 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
32830 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
32840 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
32850 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
32860 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
32870 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
32880 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
32890 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
328a0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
328b0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
328c0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
328d0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
328e0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
328f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
32900 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
32910 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
32920 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
32930 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
32940 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
32950 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
32960 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
32970 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
32980 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
32990 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
329a0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
329b0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
329c0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
329d0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
329e0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
329f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32a00 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
32a10 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
32a20 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32a30 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
32a40 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
32a50 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
32a60 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
32a70 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
32a80 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
32a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32aa0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
32ab0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
32ac0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
32ad0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
32ae0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
32af0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
32b00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32b10 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
32b20 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
32b30 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
32b40 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
32b50 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
32b60 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
32b70 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
32b80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
32b90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
32ba0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
32bb0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32bc0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32bd0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32be0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
32bf0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
32c00 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32c10 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
32c20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
32c30 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
32c40 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
32c50 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
32c60 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
32c70 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
32c80 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
32c90 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
32ca0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
32cb0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
32cc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
32cd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
32ce0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
32cf0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
32d00 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
32d10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32d20 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
32d30 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
32d40 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
32d50 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
32d60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
32d70 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
32d80 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
32d90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32da0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32db0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
32dc0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
32dd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
32de0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
32df0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
32e00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
32e10 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
32e20 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
32e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
32e40 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
32e50 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
32e60 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
32e70 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
32e80 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
32e90 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
32ea0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
32eb0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
32ec0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
32ed0 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a           1    /*
32ee0 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35   IMP: R-37514-35
32ef0 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  566 */.#define S
32f00 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
32f10 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50       2    /* IMP
32f20 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20  : R-03371-37637 
32f30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32f40 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
32f50 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   3    /* IMP: R-
32f60 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23  51971-34154 */.#
32f70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32f80 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
32f90 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
32fa0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
32fb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
32fc0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
32fd0 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a   /* Deprecated *
32fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32ff0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
33000 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
33010 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33020 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
33030 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
33040 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  on Flags.**.** T
33050 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d  hese constants m
33060 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74  ay be ORed toget
33070 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  her with the .**
33080 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
33090 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
330a0 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20  ncoding] as the 
330b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
330c0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
330d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
330e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
330f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33100 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33110 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33120 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _v2()]..*/.#defi
33130 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  ne SQLITE_DETERM
33140 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30  INISTIC    0x800
33150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33160 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
33170 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
33180 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
33190 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
331a0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
331b0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
331c0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
331d0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
331e0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
331f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
33200 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
33210 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
33220 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
33230 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
33240 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
33250 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
33260 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67  ns.  To encourag
33270 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f  e programmers to
33280 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20   avoid.** these 
33290 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69  functions, we wi
332a0 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77  ll not explain w
332b0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
332c0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
332d0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
332e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
332f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
33300 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
33310 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33320 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33330 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
33340 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
33350 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
33360 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
33370 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
33380 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
33390 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
333a0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
333b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
333c0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
333d0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
333e0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
333f0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
33400 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
33410 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33420 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
33430 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
33440 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
33450 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
33460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33470 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
33480 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
33490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
334a0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
334b0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
334c0 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
334d0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
334e0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
334f0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
33500 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
33510 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
33520 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
33530 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
33540 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
33550 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
33560 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
33570 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
33580 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
33590 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
335a0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
335b0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
335c0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
335d0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
335e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
335f0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
33600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33610 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
33620 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
33630 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
33640 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
33650 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
33660 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
33670 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
33680 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
33690 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
336a0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
336b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
336c0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
336d0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
336e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
336f0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
33700 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
33710 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
33720 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
33730 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
33740 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
33750 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33760 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
33770 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
33780 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
33790 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
337a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
337b0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
337c0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
337d0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
337e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
337f0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
33800 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
33810 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
33820 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
33830 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
33840 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
33850 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
33860 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
33870 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
33880 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
33890 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
338a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
338b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
338c0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
338d0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
338e0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
338f0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
33900 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
33910 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
33920 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
33930 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
33940 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
33950 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
33960 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
33970 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
33980 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
33990 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
339a0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
339b0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
339c0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
339d0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
339e0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
339f0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
33a00 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
33a10 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
33a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
33a30 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
33a40 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
33a50 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
33a60 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
33a70 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
33a80 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
33a90 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
33aa0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
33ab0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
33ac0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
33ad0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
33ae0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
33af0 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
33b00 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
33b10 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
33b20 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
33b30 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
33b40 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
33b50 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
33b60 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
33b70 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
33b80 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
33b90 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
33ba0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
33bb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
33bc0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
33bd0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
33be0 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
33bf0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
33c00 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
33c10 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
33c20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
33c30 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
33c40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
33c50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
33c60 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
33c70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
33c80 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
33c90 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
33ca0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
33cb0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
33cc0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
33cd0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33ce0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
33cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33d00 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
33d10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33d20 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
33d30 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
33d40 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33d50 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
33d60 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
33d70 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
33d80 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
33d90 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
33da0 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
33db0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
33dc0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
33dd0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
33de0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
33df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33e10 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
33e20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
33e30 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
33e40 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
33e50 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33e60 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
33e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33e80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
33e90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
33ea0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
33eb0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
33ec0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
33ed0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
33ee0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
33ef0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33f00 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
33f10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
33f20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33f30 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
33f40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33f50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
33f60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33f70 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
33f80 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
33f90 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
33fa0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
33fb0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33fc0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
33fd0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
33fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
33ff0 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
34000 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
34010 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34020 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
34030 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
34040 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
34050 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
34060 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
34070 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
34080 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
34090 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
340a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
340b0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
340c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
340d0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
340e0 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
340f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
34100 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
34110 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
34120 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
34130 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
34140 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
34150 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
34160 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
34170 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
34180 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
34190 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
341a0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
341b0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
341c0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
341d0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
341e0 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
341f0 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
34200 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
34210 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
34220 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
34230 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
34240 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
34250 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
34260 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
34270 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
34280 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
34290 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
342a0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
342b0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
342c0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
342d0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
342e0 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
342f0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
34300 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
34310 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
34320 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
34330 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
34340 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
34350 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
34360 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34370 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
34380 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
34390 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
343a0 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
343b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
343c0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
343d0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
343e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
343f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
34400 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
34410 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
34420 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
34430 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
34440 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
34450 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
34460 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
34470 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
34480 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
34490 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
344a0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
344b0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
344c0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
344d0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
344e0 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
344f0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
34500 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
34510 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
34520 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34530 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
34540 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
34550 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
34560 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
34570 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
34580 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
34590 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
345a0 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
345b0 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
345c0 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
345d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
345e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
345f0 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
34600 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
34610 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
34620 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
34630 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
34640 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
34650 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
34660 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
34670 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
34680 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
34690 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
346a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
346b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
346c0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
346d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
346e0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
346f0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
34700 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
34710 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
34720 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
34730 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
34740 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
34750 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
34760 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
34770 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34780 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
34790 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
347a0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
347b0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
347c0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
347d0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
347e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
347f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
34800 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34810 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
34820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
34830 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
34840 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
34850 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
34860 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
34870 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
34880 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34890 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
348a0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
348b0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
348c0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
348d0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
348e0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
348f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34900 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
34910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34920 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
34930 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
34940 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
34950 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
34960 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
34970 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
34980 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
34990 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
349a0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
349b0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
349c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
349d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
349e0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
349f0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
34a00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34a20 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
34a30 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
34a40 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
34a50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
34a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34a70 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
34a80 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
34a90 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
34aa0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
34ab0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
34ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34ad0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
34ae0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
34af0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34b00 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
34b10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34b20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
34b30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
34b40 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
34b50 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
34b60 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
34b70 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
34b80 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
34b90 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
34ba0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34bb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34bc0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
34bd0 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54  iary Data.** MET
34be0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
34bf0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
34c00 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
34c10 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
34c20 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
34c30 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
34c40 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
34c50 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
34c60 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
34c70 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
34c80 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
34c90 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
34ca0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
34cb0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
34cc0 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
34cd0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
34ce0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
34cf0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
34d00 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
34d10 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
34d20 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
34d30 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
34d40 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
34d50 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
34d60 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
34d70 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
34d80 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
34d90 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
34da0 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
34db0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
34dc0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
34dd0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
34de0 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
34df0 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
34e00 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
34e10 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
34e20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
34e30 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
34e40 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
34e50 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
34e60 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
34e70 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
34e80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34e90 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
34ea0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34eb0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
34ec0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
34ed0 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
34ee0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34ef0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
34f00 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
34f10 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
34f20 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
34f30 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34f40 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73  on. ^If there is
34f50 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20   no metadata.** 
34f60 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
34f70 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  the function arg
34f80 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69  ument, this sqli
34f90 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
34fa0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
34fb0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
34fc0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
34fd0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
34fe0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69  xdata(C,N,P,X) i
34ff0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50  nterface saves P
35000 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72   as metadata for
35010 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
35020 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
35030 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35040 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62   function.  ^Sub
35050 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
35060 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
35070 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74  auxdata(C,N) ret
35080 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d  urn P from the m
35090 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71  ost recent.** sq
350a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
350b0 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20  a(C,N,P,X) call 
350c0 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
350d0 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f  is still valid o
350e0 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65  r.** NULL if the
350f0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
35100 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  en discarded..**
35110 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c   ^After each cal
35120 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
35130 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
35140 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74  ) where X is not
35150 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65   NULL,.** SQLite
35160 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
35170 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
35180 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61  tion X with para
35190 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a  meter P exactly.
351a0 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68  ** once, when th
351b0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69  e metadata is di
351c0 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69  scarded..** SQLi
351d0 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69  te is free to di
351e0 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61  scard the metada
351f0 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20  ta at any time, 
35200 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a  including: <ul>.
35210 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65  ** <li> when the
35220 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
35230 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
35240 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a  r changes, or.**
35250 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69   <li> when [sqli
35260 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
35270 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
35280 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66  e()] is called f
35290 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53  or the.**      S
352a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  QL statement, or
352b0 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71  .** <li> when sq
352c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
352d0 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  a() is invoked a
352e0 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65  gain on the same
352f0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a   parameter, or.*
35300 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68  * <li> during th
35310 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74  e original sqlit
35320 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
35330 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d   call when a mem
35340 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c  ory .**      all
35350 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
35360 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  curs. </ul>)^.**
35370 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73  .** Note the las
35380 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74  t bullet in part
35390 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73  icular.  The des
353a0 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a  tructor X in .**
353b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
353c0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69  data(C,N,P,X) mi
353d0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d  ght be called im
353e0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
353f0 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  e the.** sqlite3
35400 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
35410 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65  nterface even re
35420 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71  turns.  Hence sq
35430 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35440 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  a().** should be
35450 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65   called near the
35460 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63   end of the func
35470 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35480 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ion and the.** f
35490 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
354a0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  tation should no
354b0 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f  t make any use o
354c0 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c  f P after.** sql
354d0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
354e0 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  () has been call
354f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
35500 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
35510 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
35520 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
35530 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e  calls for.** fun
35540 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73  ction parameters
35550 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c   that are compil
35560 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73  e-time constants
35570 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65  , including lite
35580 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
35590 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61  d [parameters] a
355a0 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63  nd expressions c
355b0 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65  omposed from the
355c0 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54   same.)^.**.** T
355d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
355e0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
355f0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
35600 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
35610 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
35620 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
35630 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
35640 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
35650 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
35660 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
35670 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
35680 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35690 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
356a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
356b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
356c0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
356d0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
356e0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
356f0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
35700 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
35710 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35720 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
35730 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
35740 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
35750 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
35760 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
35770 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
35780 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
35790 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
357a0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
357b0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
357c0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
357d0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
357e0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
357f0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
35800 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
35810 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
35820 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
35830 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
35840 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
35850 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
35860 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
35870 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
35880 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
35890 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
358a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
358b0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
358c0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
358d0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
358e0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
358f0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
35900 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
35910 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79  compilers..*/.ty
35920 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
35930 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
35940 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
35950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
35960 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
35970 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
35980 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
35990 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
359a0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
359b0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
359c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
359d0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
359e0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
359f0 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ction.** METHOD:
35a00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
35a10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35a20 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
35a30 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
35a40 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
35a50 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
35a60 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
35a70 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
35a80 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
35a90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35aa0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35ab0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35ac0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
35ad0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
35ae0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
35af0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
35b00 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
35b10 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
35b20 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
35b30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
35b40 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
35b50 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
35b60 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
35b70 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
35b80 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
35b90 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
35ba0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
35bb0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
35bc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
35bd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35be0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
35bf0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
35c00 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
35c10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35c20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35c30 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
35c40 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
35c50 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
35c60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
35c70 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
35c80 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
35c90 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
35ca0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
35cb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35cc0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
35cd0 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
35ce0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
35cf0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
35d00 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35d10 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
35d20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
35d30 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
35d40 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
35d50 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
35d60 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
35d70 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
35d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35d90 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
35da0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35db0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
35dc0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
35dd0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35de0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
35df0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
35e00 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
35e10 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
35e20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35e30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35e40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
35e50 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35e60 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
35e70 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
35e80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
35e90 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
35ea0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
35eb0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
35ec0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
35ed0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
35ee0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
35ef0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
35f00 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35f10 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
35f20 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
35f30 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
35f40 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
35f50 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
35f60 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
35f70 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
35f80 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
35f90 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
35fa0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
35fb0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
35fc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35fd0 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
35fe0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
35ff0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
36000 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
36010 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
36020 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
36030 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36040 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
36050 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
36060 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
36070 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
36080 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
36090 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
360a0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
360b0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
360c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
360d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
360e0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
360f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36100 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
36110 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
36120 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
36130 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
36140 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
36150 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
36160 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
36170 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
36180 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36190 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
361a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
361b0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
361c0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
361d0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
361e0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
361f0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
36200 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
36210 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
36220 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
36230 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
36240 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
36250 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
36260 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
36270 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36280 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
36290 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
362a0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
362b0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
362c0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
362d0 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
362e0 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
362f0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
36300 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
36310 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
36320 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
36330 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36340 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
36350 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
36360 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
36370 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
36380 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
36390 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
363a0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
363b0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
363c0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
363d0 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
363e0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
363f0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
36400 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
36410 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
36420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36430 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
36440 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
36450 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
36460 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
36470 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
36480 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36490 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
364a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
364b0 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
364c0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
364d0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
364e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
364f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36500 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
36510 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
36520 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
36530 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
36540 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
36550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
36560 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
36570 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36580 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36590 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
365a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
365b0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
365c0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
365d0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
365e0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
365f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36600 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
36610 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
36620 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36630 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
36640 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36650 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
36660 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
36670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36680 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
36690 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
366a0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
366b0 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
366c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
366d0 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
366e0 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
366f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
36700 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36710 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36720 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
36730 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
36740 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
36750 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
36760 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
36770 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
36780 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
36790 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
367a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
367b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
367c0 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69  esult_text64() i
367d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
367e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
367f0 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  f an.** applicat
36800 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36810 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78  tion to be a tex
36820 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65  t string in an e
36830 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69  ncoding.** speci
36840 66 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74  fied by the fift
36850 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72  h (and last) par
36860 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75  ameter, which mu
36870 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20  st be one.** of 
36880 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
36890 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
368a0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
368b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
368c0 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  6LE]..** ^SQLite
368d0 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
368e0 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
368f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
36900 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
36910 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
36920 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36930 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
36940 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
36950 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36960 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36970 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
36980 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
36990 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
369a0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
369b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
369c0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
369d0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
369e0 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
369f0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36a00 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
36a10 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36a20 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
36a30 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
36a40 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
36a50 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
36a60 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
36a70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
36a80 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
36a90 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
36aa0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36ab0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
36ac0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
36ad0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
36ae0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
36af0 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
36b00 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
36b10 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
36b20 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
36b30 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
36b40 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
36b50 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
36b60 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
36b70 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
36b80 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
36b90 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
36ba0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
36bb0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
36bc0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
36bd0 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
36be0 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
36bf0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
36c00 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
36c10 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
36c20 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
36c30 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
36c40 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
36c50 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
36c60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
36c70 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
36c80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
36c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36ca0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
36cb0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
36cc0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
36cd0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
36ce0 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
36cf0 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
36d00 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
36d10 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
36d20 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
36d30 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
36d40 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
36d50 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
36d60 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
36d70 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
36d80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36d90 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
36da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
36db0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
36dc0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
36dd0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
36de0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
36df0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
36e00 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
36e10 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
36e20 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
36e30 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
36e40 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
36e50 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
36e60 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
36e70 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
36e80 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
36e90 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
36ea0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
36eb0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
36ec0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
36ed0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36ee0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
36ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36f00 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
36f10 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
36f20 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
36f30 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
36f40 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
36f50 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
36f60 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
36f70 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
36f80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
36f90 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
36fa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36fb0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
36fc0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36fd0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
36fe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36ff0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37000 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
37010 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
37020 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
37030 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
37040 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
37050 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
37060 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37070 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
37080 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
37090 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
370a0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
370b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
370c0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
370d0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
370e0 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
370f0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
37100 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
37110 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
37120 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
37130 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
37140 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37150 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
37160 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
37170 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
37180 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
37190 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
371a0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
371b0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
371c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
371d0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
371e0 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
371f0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
37200 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
37210 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
37220 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
37230 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
37240 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
37250 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
37260 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37270 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
37280 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
37290 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
372a0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
372b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
372c0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
372d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
372e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
372f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
37300 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
37310 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37320 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c  esult_blob64(sql
37330 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f  ite3_context*,co
37340 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20  nst void*,.     
37350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37360 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 75 69        sqlite3_ui
37370 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69  nt64,void(*)(voi
37380 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
37390 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
373a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
373b0 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
373c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
373d0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
373e0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
373f0 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
37400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37410 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
37420 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37430 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
37440 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37450 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
37460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37470 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37480 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
37490 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
374a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
374b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
374c0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
374d0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
374e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
374f0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
37500 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
37510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37520 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
37530 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
37540 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
37550 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
37560 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
37570 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37580 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
37590 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
375a0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
375b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
375c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
375d0 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ult_text64(sqlit
375e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
375f0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
37600 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
37610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37620 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
37630 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
37640 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69  r encoding);.voi
37650 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37660 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
37670 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37680 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
37690 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
376a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
376b0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
376c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
376d0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
376e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
376f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37700 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
37710 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37720 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
37730 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
37740 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37750 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
37760 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
37770 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
37780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37790 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
377a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
377b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
377c0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
377d0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
377e0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
377f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
37800 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
37810 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
37820 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
37830 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
37840 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
37850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
37860 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
37870 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
37880 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
37890 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
378a0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
378b0 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
378c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
378d0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
378e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
378f0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
37900 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
37910 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
37920 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
37930 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
37940 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
37950 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
37960 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
37970 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
37980 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
37990 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
379a0 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
379b0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
379c0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
379d0 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
379e0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
379f0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
37a00 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
37a10 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
37a20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37a30 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
37a40 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
37a50 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
37a60 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
37a70 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
37a80 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
37a90 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
37aa0 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
37ab0 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
37ac0 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
37ad0 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
37ae0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37af0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
37b00 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
37b10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
37b20 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
37b30 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
37b40 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
37b50 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
37b60 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
37b70 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
37b80 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
37b90 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
37ba0 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
37bb0 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
37bc0 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
37bd0 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
37be0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
37bf0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
37c00 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
37c10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
37c20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
37c30 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
37c40 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
37c50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
37c60 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37c70 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
37c80 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
37c90 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
37ca0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
37cb0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
37cc0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
37cd0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
37ce0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
37cf0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
37d00 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
37d10 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
37d20 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
37d30 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
37d40 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
37d50 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
37d60 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
37d70 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
37d80 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
37d90 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
37da0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
37db0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
37dc0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
37dd0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
37de0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
37df0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
37e00 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
37e10 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
37e20 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
37e30 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
37e40 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
37e50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
37e60 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
37e80 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
37e90 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
37ea0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
37eb0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
37ec0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
37ed0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
37ee0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
37ef0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
37f00 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
37f10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
37f20 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
37f30 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
37f40 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
37f50 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
37f60 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
37f70 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
37f80 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
37f90 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
37fa0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
37fb0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
37fc0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
37fd0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
37fe0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
37ff0 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
38000 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
38010 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
38020 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
38030 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
38040 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
38050 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
38060 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
38070 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
38080 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
38090 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
380a0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
380b0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
380c0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
380d0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
380e0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
380f0 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
38100 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
38110 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
38120 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
38130 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
38140 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
38150 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
38160 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
38170 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
38180 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
38190 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
381a0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
381b0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
381c0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
381d0 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
381e0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
381f0 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
38200 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
38210 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
38220 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
38230 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
38240 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
38250 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
38260 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
38270 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38280 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38290 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
382a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
382b0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
382c0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
382d0 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
382e0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
382f0 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
38300 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
38310 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
38320 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
38330 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
38340 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
38350 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
38360 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
38370 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
38380 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
38390 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
383a0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
383b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
383c0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
383d0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
383e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
383f0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
38400 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
38410 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
38420 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
38430 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
38440 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
38450 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
38460 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
38470 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
38480 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
38490 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
384a0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
384b0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
384c0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
384d0 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
384e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
384f0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
38500 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
38510 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
38520 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
38530 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
38540 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
38550 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
38560 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
38570 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
38580 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
38590 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
385a0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
385b0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
385c0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
385d0 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
385e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
385f0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
38600 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
38610 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
38620 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
38630 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
38640 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38650 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
38660 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
38670 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
38680 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
38690 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
386a0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
386b0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
386c0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
386d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
386e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
386f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
38700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
38710 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
38720 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
38730 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
38740 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
38750 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
38760 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
38770 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
38780 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
38790 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
387a0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
387b0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
387c0 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
387d0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
387e0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
387f0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
38800 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
38810 2c 69 6e 74 2