/ Hex Artifact Content
Login

Artifact a57fba23bfa1b17e60e6bd682f9614ab59272390:


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 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52  LITE_OPEN_FILEPR
6310: 4f 54 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20  OTECTION_MASK   
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6340: 30 30 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73  00700000../* Res
6350: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6370: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
6380: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
6390: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
63a0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
63b0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
63c0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
63d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
63e0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
63f0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
6400: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
6410: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
6420: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
6430: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6440: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6450: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6460: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6470: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
6480: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
6490: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
64a0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
64b0: 2a 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 20 70 72 6f 70 65 72  AP_ATOMIC proper
64d0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
64e0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
64f0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
6500: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6510: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
6520: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
6530: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6540: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6550: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6560: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6570: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6580: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6590: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
65a0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
65b0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
65c0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
65d0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
65e0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
65f0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
6600: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
6610: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
6620: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
6630: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6640: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6650: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6660: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6670: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6680: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6690: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
66a0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
66b0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
66c0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
66d0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
66e0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
66f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6700: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
6710: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6720: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
6730: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6740: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6750: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6760: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6770: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6780: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6790: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
67a0: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
67b0: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
67c0: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
67d0: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
67e0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
67f0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
6800: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20   be unchanged.  
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6820: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6830: 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69  N_OPEN.** flag i
6840: 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66  ndicate that a f
6850: 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65  ile cannot be de
6860: 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e  leted when open.
6870: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f    The.** SQLITE_
6880: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6890: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74  flag indicates t
68a0: 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20  hat the file is 
68b0: 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20  on.** read-only 
68c0: 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74  media and cannot
68d0: 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e   be changed even
68e0: 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69   by processes wi
68f0: 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70  th.** elevated p
6900: 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64  rivileges..*/.#d
6910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6920: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6930: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6940: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6950: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6960: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6970: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6990: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
69a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69b0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
69c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
69d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
69e0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
69f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a00: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6a10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a50: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
6a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a70: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6a80: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6aa0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6ab0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ac0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6ad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ae0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6af0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b10: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6b20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b30: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6b40: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6b50: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
6b60: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
6b70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b80: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6b90: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6ba0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bb0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6bc0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6bd0: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
6be0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6bf0: 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  MUTABLE         
6c00: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
6c10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c20: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6c30: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6c40: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6c50: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6c60: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6c70: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6c80: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6c90: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
6ca0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
6cb0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6cc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6cd0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6cf0: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d10: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6d20: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6d30: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6d40: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6d50: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
6d60: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
6d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6d80: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
6d90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6da0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
6db0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6dc0: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6dd0: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6de0: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6e00: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6e10: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6e20: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6e30: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6e40: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6e50: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6e60: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6e70: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6e80: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6e90: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6ea0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6eb0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6ec0: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6ed0: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6ee0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6ef0: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6f00: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6f10: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6f20: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6f30: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6f40: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6f50: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6f60: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6f70: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6f80: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6f90: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6fa0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6fb0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6fc0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6fd0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6fe0: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6ff0: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
7000: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7010: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7020: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
7030: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
7040: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
7050: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
7060: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
7070: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
7080: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7090: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
70a0: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
70b0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
70c0: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
70d0: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
70e0: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
70f0: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
7100: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7110: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7120: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
7130: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
7140: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
7150: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
7160: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
7170: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
7180: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7190: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
71a0: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
71b0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
71c0: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
71d0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
71e0: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
71f0: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
7200: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
7210: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7220: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7230: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
7240: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
7250: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
7260: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
7270: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
7280: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7290: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
72a0: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
72b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
72c0: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
72d0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
72e0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
72f0: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
7300: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7310: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
7320: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
7330: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7340: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
7350: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
7360: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7370: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7380: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7390: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
73a0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
73b0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
73c0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
73d0: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
73e0: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
73f0: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7400: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7410: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7420: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7430: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7440: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7450: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
7460: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7470: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7480: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7490: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
74a0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
74b0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
74c0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
74d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
74e0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
74f0: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7500: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7510: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7520: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7530: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7540: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7550: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
7560: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7570: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7580: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7590: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
75a0: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
75b0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
75c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
75d0: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
75e0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
75f0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7600: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7610: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7620: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7630: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7640: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7650: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
7660: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7670: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7680: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7690: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
76a0: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
76b0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
76c0: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
76d0: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
76e0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
76f0: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7700: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7710: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7720: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7730: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7740: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7750: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
7760: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7770: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7780: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7790: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
77a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
77b0: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
77c0: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
77d0: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
77e0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
77f0: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7800: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7810: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7820: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7830: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7840: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7850: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7860: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7870: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7880: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7890: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
78a0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
78b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
78c0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
78d0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
78e0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
78f0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7900: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7910: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7920: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7930: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7940: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7950: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
7960: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7970: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7980: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7990: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
79a0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
79b0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
79c0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
79d0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
79e0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
79f0: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7a00: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7a10: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7a20: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a30: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7a40: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a50: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
7a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a70: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7a80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a90: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
7aa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
7ab0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7ac0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7ad0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7ae0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7af0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7b00: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7b10: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7b20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7b30: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7b40: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7b50: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7b60: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7b70: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7b80: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7b90: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
7ba0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
7bb0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7bc0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7bd0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7be0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7bf0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7c00: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7c10: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7c20: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7c30: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7c40: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7c50: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7c60: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7c70: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7c80: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7c90: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
7ca0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
7cb0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7cc0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7cd0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7ce0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7cf0: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7d00: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7d10: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7d20: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7d30: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7d40: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7d50: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
7d60: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
7d70: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
7d80: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
7d90: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
7da0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
7db0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7dc0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7dd0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7de0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7df0: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7e00: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7e10: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7e20: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7e30: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7e40: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7e50: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7e60: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7e70: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7e80: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7e90: 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20  use..** A [file 
7ea0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
7eb0: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
7ec0: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
7ed0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
7ee0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
7ef0: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
7f00: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
7f10: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
7f20: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
7f30: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
7f40: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
7f50: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
7f60: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
7f70: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
7f80: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
7f90: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
7fa0: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
7fb0: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
7fc0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
7fd0: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
7fe0: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
7ff0: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
8000: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
8010: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
8020: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
8030: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
8040: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
8050: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
8060: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
8070: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
8080: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
8090: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
80a0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
80b0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
80c0: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
80d0: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
80e0: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
80f0: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
8100: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8110: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8120: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
8130: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8140: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
8150: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8160: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
8170: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8180: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
8190: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81a0: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
81b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81c0: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
81d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81e0: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
81f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8200: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
8210: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8220: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
8230: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8240: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
8250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8260: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8270: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
8280: 2a 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 20 70 72 6f 70 65 72  AP_ATOMIC proper
82a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
82b0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
82c0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
82d0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
82e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
82f0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
8300: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
8310: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
8320: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
8330: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
8340: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
8350: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
8360: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
8370: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
8380: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
8390: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
83a0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
83b0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
83c0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
83d0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
83e0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
83f0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
8400: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
8410: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
8420: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
8430: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8450: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
8460: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
8470: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
8480: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
8490: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
84a0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
84b0: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  Write()..**.** I
84c0: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e  f xRead() return
84d0: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  s SQLITE_IOERR_S
84e0: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73  HORT_READ it mus
84f0: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69  t also fill.** i
8500: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72  n the unread por
8510: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66  tions of the buf
8520: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  fer with zeros. 
8530: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66   A VFS that.** f
8540: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  ails to zero-fil
8550: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69  l short reads mi
8560: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b  ght seem to work
8570: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
8580: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66  ailure to zero-f
8590: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
85a0: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
85b0: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62  lead to.** datab
85c0: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  ase corruption..
85d0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
85e0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
85f0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
8600: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
8610: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8620: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
8630: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
8640: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
8650: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
8660: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
8670: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
8680: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
8690: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
86a0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
86b0: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
86c0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
86d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
86e0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
86f0: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
8700: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8710: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
8720: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
8730: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
8740: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
8750: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
8760: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8770: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
8780: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
8790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
87a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
87b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
87c0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
87d0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
87e0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
87f0: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
8800: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
8810: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
8820: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
8830: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
8840: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
8850: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8860: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
8870: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8880: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
8890: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
88a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
88b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f  for version 1 */
88c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70  .  int (*xShmMap
88d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
88e0: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67   int iPg, int pg
88f0: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f  sz, int, void vo
8900: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
8910: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
8920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8930: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
8940: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69  nt flags);.  voi
8950: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29  d (*xShmBarrier)
8960: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8970: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d  .  int (*xShmUnm
8980: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8990: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
89a0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
89b0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
89c0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
89d0: 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68  /.  int (*xFetch
89e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89f0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8a00: 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20  Ofst, int iAmt, 
8a10: 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e  void **pp);.  in
8a20: 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71  t (*xUnfetch)(sq
8a30: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8a40: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8a50: 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a  , void *p);.  /*
8a60: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8a70: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8a80: 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41  sion 3 */.  /* A
8a90: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
8aa0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
8ab0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
8ac0: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
8ad0: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
8ae0: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
8af0: 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  pcodes.** KEYWOR
8b00: 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f  DS: {file contro
8b10: 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65  l opcodes} {file
8b20: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d   control opcode}
8b30: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
8b40: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
8b50: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
8b60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8b70: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
8b80: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8b90: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
8ba0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
8bb0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8bc0: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
8bd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
8be0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8bf0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20  _LOCKSTATE]].** 
8c00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8c10: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8c20: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8c30: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8c40: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8c50: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8c60: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8c70: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8c80: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8c90: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8ca0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8cb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8cc0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8cd0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8ce0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8cf0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8d00: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8d10: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8d20: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8d30: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8d40: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8d50: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8d60: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8d70: 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61  ng and is only a
8d80: 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68  vailable when th
8d90: 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  e SQLITE_TEST.**
8da0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
8db0: 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
8dc0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8dd0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8de0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8df0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8e00: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8e10: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8e20: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8e30: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8e40: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8e50: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8e60: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8e70: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8e80: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8e90: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8ea0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8eb0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8ec0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8ed0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8ee0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8ef0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8f00: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8f10: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8f20: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8f30: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8f40: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8f50: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8f60: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8f70: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8f80: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8f90: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8fa0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8fb0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8fc0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8fd0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8fe0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8ff0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9000: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
9010: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
9020: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
9030: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
9040: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
9050: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9060: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
9070: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
9080: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
9090: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
90a0: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
90b0: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
90c0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
90d0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
90e0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
90f0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
9100: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
9110: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
9120: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
9130: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
9140: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
9150: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
9160: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
9170: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9180: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
9190: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
91a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
91b0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
91c0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
91d0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
91e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
91f0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9200: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
9210: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
9220: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
9230: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9240: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
9250: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
9260: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
9270: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
9280: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9290: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
92a0: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
92b0: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
92c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
92d0: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
92e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
92f0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9300: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9310: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
9320: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9330: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9340: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9350: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9360: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
9370: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
9380: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
9390: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
93a0: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
93b0: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
93c0: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
93d0: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
93e0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
93f0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
9400: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
9410: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9420: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9430: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9440: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9450: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9460: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
9470: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9480: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
9490: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
94a0: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
94b0: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
94c0: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
94d0: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
94e0: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
94f0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
9500: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
9510: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9520: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9530: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9540: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9550: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9560: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
9570: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9580: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9590: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
95a0: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
95b0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
95c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
95d0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
95e0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
95f0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
9600: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9610: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9620: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9630: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9640: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9650: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9660: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9670: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9680: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
9690: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
96a0: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
96b0: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
96c0: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
96d0: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
96e0: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
96f0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
9700: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
9710: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9720: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9730: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9740: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9750: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9760: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9770: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
9780: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
9790: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
97a0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
97b0: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
97c0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
97d0: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
97e0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
97f0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9800: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9810: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9820: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9830: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9840: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9850: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9860: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9870: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9880: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9890: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
98a0: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
98b0: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
98c0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
98d0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
98e0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
98f0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
9900: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
9910: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9920: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9930: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
9940: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
9950: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
9960: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
9970: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
9980: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9990: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
99a0: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
99b0: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
99c0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
99d0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
99e0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
99f0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
9a00: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
9a10: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
9a20: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
9a30: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
9a40: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
9a50: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
9a60: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
9a70: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
9a80: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9a90: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9aa0: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9ab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9ac0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9ad0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9ae0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9af0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9b00: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9b10: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9b20: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
9b30: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
9b40: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
9b50: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
9b60: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
9b70: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
9b80: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9b90: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9ba0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9bb0: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9bc0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9bd0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9be0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9bf0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9c00: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9c10: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9c20: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
9c30: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
9c40: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
9c50: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
9c60: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c70: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9c80: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9c90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9ca0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9cb0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9cc0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9cd0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9ce0: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9cf0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9d00: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9d10: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9d20: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
9d30: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d40: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
9d50: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
9d60: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
9d70: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
9d80: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9d90: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9da0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9db0: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9dc0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9dd0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
9de0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
9df0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
9e00: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
9e10: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
9e20: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
9e30: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
9e40: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
9e50: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
9e60: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
9e70: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
9e80: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
9e90: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
9ea0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
9eb0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
9ec0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
9ed0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
9ee0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
9ef0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
9f00: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
9f10: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
9f20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9f30: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
9f40: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
9f50: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
9f60: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
9f70: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
9f80: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
9f90: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
9fa0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
9fb0: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
9fc0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9fd0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9fe0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9ff0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a000: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a010: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a020: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a040: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a050: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a060: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a070: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a080: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a090: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a0a0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a0b0: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a0c0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a0d0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a0e0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a0f0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a100: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a110: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a120: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a130: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a140: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a150: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a160: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a170: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a180: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a190: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a1a0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a1b0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a1c0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a1d0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a1e0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a1f0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a200: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a210: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a220: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a230: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a240: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a250: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a260: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a280: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a290: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a2a0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a2b0: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a2c0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a2d0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a2e0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a2f0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a300: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a310: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a320: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a330: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a340: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
a350: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
a360: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
a370: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
a380: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a390: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a3a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a3b0: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a3c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3d0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a3e0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a3f0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a400: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a410: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a420: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a430: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a440: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a450: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a460: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a470: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a480: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a490: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a4a0: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a4b0: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a4c0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a4d0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a4e0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a4f0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a500: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a510: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a520: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a530: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a540: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a550: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a560: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a570: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a580: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a590: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a5a0: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a5b0: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a5c0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a5d0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a5e0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a5f0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a600: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a610: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a620: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a630: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a640: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a650: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a660: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a670: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a680: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
a690: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
a6a0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
a6b0: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
a6c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
a6d0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a6e0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
a6f0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
a700: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
a710: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
a720: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a730: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
a740: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
a750: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
a760: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
a770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a780: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a790: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
a7a0: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
a7b0: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
a7c0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
a7d0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
a7e0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
a7f0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
a800: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
a810: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
a820: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
a830: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
a840: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
a850: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
a860: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
a870: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
a880: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a890: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
a8a0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
a8b0: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
a8c0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
a8d0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
a8e0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
a8f0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
a900: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
a910: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
a920: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
a930: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
a940: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
a950: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
a960: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
a970: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
a980: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
a990: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
a9a0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a9b0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a9c0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a9d0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
a9e0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
a9f0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
aa00: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
aa10: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa20: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa30: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
aa40: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
aa50: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
aa60: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
aa70: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
aa80: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
aa90: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
aaa0: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
aab0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
aac0: 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72  nt if result str
aad0: 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20  ing is NULL, or 
aae0: 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63  that returns a c
aaf0: 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  opy.** of the re
ab00: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74  sult string if t
ab10: 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e  he string is non
ab20: 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68  -NULL..** ^If th
ab30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ab40: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ab50: 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20  trol returns.** 
ab60: 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  any result code 
ab70: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
ab80: 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54  TE_OK] or [SQLIT
ab90: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61  E_NOTFOUND], tha
aba0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  t means.** that 
abb0: 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65  the VFS encounte
abc0: 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69  red an error whi
abd0: 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20  le handling the 
abe0: 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65  [PRAGMA] and the
abf0: 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  .** compilation 
ac00: 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61  of the PRAGMA fa
ac10: 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ils with an erro
ac20: 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  r.  ^The [SQLITE
ac30: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
ac40: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  * file control o
ac50: 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67  ccurs at the beg
ac60: 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61  inning of pragma
ac70: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79   statement analy
ac80: 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74  sis and so.** it
ac90: 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72   is able to over
aca0: 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50  ride built-in [P
acb0: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
acc0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
acd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
ace0: 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68  HANDLER]].** ^Th
acf0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ad00: 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20  BUSYHANDLER].** 
ad10: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79  file-control may
ad20: 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   be invoked by S
ad30: 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74  QLite on the dat
ad40: 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c  abase file handl
ad50: 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74  e.** shortly aft
ad60: 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20  er it is opened 
ad70: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
ad80: 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53  ide a custom VFS
ad90: 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20   with access.** 
ada0: 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  to the connectio
adb0: 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  ns busy-handler 
adc0: 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72  callback. The ar
add0: 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70  gument is of typ
ade0: 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d  e (void **).** -
adf0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
ae00: 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73   (void *) values
ae10: 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69  . The first (voi
ae20: 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f  d *) actually po
ae30: 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e  ints.** to a fun
ae40: 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69  ction of type (i
ae50: 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e  nt (*)(void *)).
ae60: 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76   In order to inv
ae70: 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  oke the connecti
ae80: 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64  ons.** busy-hand
ae90: 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ler, this functi
aea0: 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76  on should be inv
aeb0: 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65  oked with the se
aec0: 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e  cond (void *) in
aed0: 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73  .** the array as
aee0: 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65   the only argume
aef0: 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  nt. If it return
af00: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
af10: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
af20: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72  * should be retr
af30: 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72  ied. If it retur
af40: 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73  ns zero, the cus
af50: 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61  tom VFS should a
af60: 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75  bandon the.** cu
af70: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e  rrent operation.
af80: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
af90: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
afa0: 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70  LENAME]].** ^App
afb0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76  lication can inv
afc0: 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  oke the [SQLITE_
afd0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
afe0: 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  ME] file-control
aff0: 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69  .** to have SQLi
b000: 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a  te generate a.**
b010: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b020: 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ame using the sa
b030: 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61  me algorithm tha
b040: 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f  t is followed to
b050: 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d   generate.** tem
b060: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73  porary filenames
b070: 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73   for TEMP tables
b080: 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72   and other inter
b090: 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a  nal uses.  The.*
b0a0: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
b0b0: 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68  d be a char** wh
b0c0: 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c  ich will be fill
b0d0: 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65  ed with the file
b0e0: 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20  name.** written 
b0f0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
b100: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
b110: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
b120: 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64  he caller should
b130: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  .** invoke [sqli
b140: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74  te3_free()] on t
b150: 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f  he result to avo
b160: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  id a memory leak
b170: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b180: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b190: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
b1a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b1b0: 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
b1c0: 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71  rol is used to q
b1d0: 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a  uery or set the.
b1e0: 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ** maximum numbe
b1f0: 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20  r of bytes that 
b200: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72  will be used for
b210: 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49   memory-mapped I
b220: 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  /O..** The argum
b230: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
b240: 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74   to a value of t
b250: 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ype sqlite3_int6
b260: 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20  4 that.** is an 
b270: 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d  advisory maximum
b280: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b290: 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20   in the file to 
b2a0: 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65  memory map.  The
b2b0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f  .** pointer is o
b2c0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
b2d0: 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20  the old value.  
b2e0: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  The limit is not
b2f0: 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74   changed if.** t
b300: 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61  he value origina
b310: 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69  lly pointed to i
b320: 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20  s negative, and 
b330: 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c  so the current l
b340: 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20  imit .** can be 
b350: 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69  queried by passi
b360: 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20  ng in a pointer 
b370: 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  to a negative nu
b380: 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66  mber.  This.** f
b390: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile-control is u
b3a0: 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
b3b0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41  o implement [PRA
b3c0: 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a  GMA mmap_size]..
b3d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3e0: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d  TE_FCNTL_TRACE]]
b3f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b400: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c  FCNTL_TRACE] fil
b410: 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64  e control provid
b420: 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f  es advisory info
b430: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68  rmation.** to th
b440: 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74  e VFS about what
b450: 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65   the higher laye
b460: 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  rs of the SQLite
b470: 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67   stack are doing
b480: 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63  ..** This file c
b490: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62  ontrol is used b
b4a0: 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76  y some VFS activ
b4b0: 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69  ity tracing [shi
b4c0: 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ms]..** The argu
b4d0: 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74  ment is a zero-t
b4e0: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
b4f0: 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73  .  Higher layers
b500: 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74   in the.** SQLit
b510: 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65  e stack may gene
b520: 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f  rate instances o
b530: 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  f this file cont
b540: 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53  rol if.** the [S
b550: 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f  QLITE_USE_FCNTL_
b560: 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
b570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
b580: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  abled..**.** <li
b590: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b5a0: 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54  HAS_MOVED]].** T
b5b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b5c0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65  _HAS_MOVED] file
b5d0: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
b5e0: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
b5f0: 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   as a.** pointer
b600: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
b610: 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62  nd it writes a b
b620: 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74  oolean into that
b630: 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69   integer dependi
b640: 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  ng.** on whether
b650: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   or not the file
b660: 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65   has been rename
b670: 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c  d, moved, or del
b680: 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a  eted since it.**
b690: 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65   was first opene
b6a0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
b6b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
b6c0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a  2_SET_HANDLE]].*
b6d0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b6e0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
b6f0: 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  NDLE] opcode is 
b700: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
b710: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
b720: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
b730: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
b740: 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66  od to swap the f
b750: 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20  ile handle with 
b760: 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74  the one.** point
b770: 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72  ed to by the pAr
b780: 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69  g argument.  Thi
b790: 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20  s capability is 
b7a0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
b7b0: 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20  ing.** and only 
b7c0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
b7d0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
b7e0: 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65  E_TEST is define
b7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
b800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
b810: 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b  BLOCK]].** The [
b820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
b830: 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67  _BLOCK] is a sig
b840: 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c  nal to the VFS l
b850: 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67  ayer that it mig
b860: 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61  ht.** be advanta
b870: 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f  geous to block o
b880: 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c  n the next WAL l
b890: 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20  ock if the lock 
b8a0: 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65  is not immediate
b8b0: 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e  ly.** available.
b8c0: 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73    The WAL subsys
b8d0: 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20  tem issues this 
b8e0: 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61  signal during ra
b8f0: 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e  re.** circumstan
b900: 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ces in order to 
b910: 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69  fix a problem wi
b920: 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65  th priority inve
b930: 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63  rsion..** Applic
b940: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65  ations should <e
b950: 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74  m>not</em> use t
b960: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
b970: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ..**.** </ul>.*/
b980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b990: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
b9b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9c0: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
b9d0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
b9e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b9f0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
ba00: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
ba10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba20: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
ba30: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
ba40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba50: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
ba60: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
ba70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ba80: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
ba90: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
baa0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bab0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
bac0: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
bad0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bae0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
baf0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
bb00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
bb10: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
bb20: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
bb30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
bb40: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
bb50: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
bb60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
bb70: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
bb80: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
bb90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
bba0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
bbb0: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
bbc0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
bbd0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
bbe0: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
bbf0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
bc00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bc10: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
bc20: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
bc30: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
bc40: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
bc50: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
bc60: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
bc70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc80: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
bc90: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
bca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bcb0: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
bcc0: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
bcd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bce0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
bcf0: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
bd00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd10: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
bd20: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
bd30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd40: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
bd50: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
bd60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd70: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
bd80: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
bd90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bda0: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
bdb0: 20 20 20 20 20 20 20 32 34 0a 0a 2f 2a 20 64 65         24../* de
bdc0: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
bdd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bde0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
bdf0: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
be00: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
be10: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
be20: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
be30: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
be50: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
be60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
be70: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
be80: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
be90: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
bea0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
beb0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
bec0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
bed0: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
bee0: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
bef0: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
bf00: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
bf10: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
bf20: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
bf30: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
bf40: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
bf50: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
bf60: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
bf70: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
bf80: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
bf90: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
bfa0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
bfb0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
bfc0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
bfd0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
bfe0: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
bff0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
c000: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
c010: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
c020: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c030: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
c040: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
c050: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
c060: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
c070: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
c080: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
c090: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
c0a0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
c0b0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
c0c0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
c0d0: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
c0e0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
c0f0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
c100: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
c110: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
c120: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
c130: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
c140: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
c150: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
c160: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
c170: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
c180: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
c190: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
c1a0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
c1b0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
c1c0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
c1d0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
c1e0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
c1f0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
c200: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
c210: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
c220: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
c230: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
c240: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
c250: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
c260: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
c270: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
c280: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
c290: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
c2a0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
c2b0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
c2c0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
c2d0: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
c2e0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
c2f0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
c300: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
c310: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
c320: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
c330: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
c340: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
c350: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
c360: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
c370: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
c380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
c390: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
c3a0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
c3b0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
c3c0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
c3d0: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
c3e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
c3f0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
c400: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
c410: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
c420: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
c430: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
c440: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
c450: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
c460: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
c470: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
c480: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
c490: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
c4a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
c4b0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
c4c0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
c4d0: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
c4e0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
c4f0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
c500: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
c510: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
c520: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
c530: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
c540: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
c550: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
c560: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
c570: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
c580: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
c590: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
c5a0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
c5b0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
c5c0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
c5d0: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
c5e0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
c5f0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
c600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
c610: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
c620: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
c630: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
c640: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
c650: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
c660: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
c670: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
c680: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
c690: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
c6a0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
c6b0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
c6c0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
c6d0: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
c6e0: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
c6f0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
c700: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
c710: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
c720: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
c730: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
c740: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
c750: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
c760: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
c770: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
c780: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
c790: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
c7a0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
c7b0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
c7c0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
c7d0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
c7e0: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
c7f0: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
c800: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
c810: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
c820: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
c830: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
c840: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
c850: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
c860: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
c870: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
c880: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
c890: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
c8a0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
c8b0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
c8c0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
c8d0: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
c8e0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
c8f0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
c900: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
c910: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
c920: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
c930: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
c940: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
c950: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
c960: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
c970: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
c980: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
c990: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
c9a0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
c9b0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
c9c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
c9d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
c9e0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
c9f0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
ca00: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
ca10: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
ca20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ca30: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
ca40: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
ca50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
ca60: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
ca70: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
ca80: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
ca90: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
caa0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
cab0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
cac0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
cad0: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
cae0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
caf0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
cb00: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
cb10: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
cb20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
cb30: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
cb40: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
cb50: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
cb60: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
cb70: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
cb80: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
cb90: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
cba0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
cbb0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
cbc0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
cbd0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
cbe0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cbf0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
cc00: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cc10: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
cc20: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cc30: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
cc40: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cc50: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
cc60: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
cc70: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
cc80: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
cc90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
cca0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ccb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
ccc0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
ccd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cce0: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
ccf0: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
cd00: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
cd10: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
cd20: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
cd30: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
cd40: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
cd50: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
cd60: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
cd70: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
cd80: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
cd90: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
cda0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
cdb0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
cdc0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
cdd0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
cde0: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
cdf0: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
ce00: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
ce10: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
ce20: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
ce30: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
ce40: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
ce50: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
ce60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
ce70: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
ce80: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
ce90: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
cea0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
ceb0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
cec0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
ced0: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
cee0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
cef0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
cf00: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
cf10: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
cf20: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
cf30: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
cf40: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
cf50: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
cf60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
cf70: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
cf80: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
cf90: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
cfa0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
cfb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
cfc0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
cfd0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
cfe0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
cff0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
d000: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
d010: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
d020: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d030: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
d040: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
d050: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
d060: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
d070: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
d080: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
d090: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
d0a0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d0b0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
d0c0: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
d0d0: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
d0e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
d0f0: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
d100: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
d110: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
d120: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
d130: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
d140: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
d150: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
d160: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
d170: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
d180: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
d190: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
d1a0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
d1b0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d1c0: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
d1d0: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
d1e0: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
d1f0: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
d200: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
d210: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
d220: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
d230: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
d240: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
d250: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
d260: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
d270: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
d280: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
d290: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
d2a0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
d2b0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
d2c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
d2d0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
d2e0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
d2f0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
d300: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
d310: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
d320: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
d330: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
d340: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
d350: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
d360: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
d370: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
d380: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
d390: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
d3a0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
d3b0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
d3c0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
d3d0: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
d3e0: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
d3f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
d400: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
d410: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
d420: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d430: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
d440: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
d450: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
d460: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
d470: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
d480: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
d490: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
d4a0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
d4b0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
d4c0: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
d4d0: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
d4e0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
d4f0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
d500: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
d510: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
d520: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
d530: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
d540: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
d550: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
d560: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
d570: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
d580: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
d590: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
d5a0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
d5b0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
d5c0: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
d5d0: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
d5e0: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
d5f0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
d600: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
d610: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
d620: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
d630: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
d640: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
d650: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
d660: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
d670: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
d680: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
d690: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
d6a0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
d6b0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
d6c0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
d6d0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
d6e0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
d6f0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
d700: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
d710: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
d720: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
d730: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
d740: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
d750: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
d760: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
d770: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
d780: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
d790: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
d7a0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
d7b0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
d7c0: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
d7d0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
d7e0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
d7f0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
d800: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
d810: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
d820: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
d830: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
d840: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
d850: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
d860: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
d870: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
d880: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
d890: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
d8a0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
d8b0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
d8c0: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
d8d0: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
d8e0: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
d8f0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
d900: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
d910: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
d920: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
d930: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
d940: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
d950: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
d960: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
d970: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
d980: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
d990: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
d9a0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
d9b0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
d9c0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
d9d0: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
d9e0: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
d9f0: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
da00: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
da10: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
da20: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
da30: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
da40: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
da50: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
da60: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
da70: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
da80: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
da90: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
daa0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
dab0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
dac0: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
dad0: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
dae0: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
daf0: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
db00: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
db10: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
db20: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
db30: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
db40: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
db50: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
db60: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
db70: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
db80: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
db90: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
dba0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
dbb0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
dbc0: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
dbd0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
dbe0: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
dbf0: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
dc00: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
dc10: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
dc20: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
dc30: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
dc40: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
dc50: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
dc60: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
dc70: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
dc80: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
dc90: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
dca0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
dcb0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
dcc0: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
dcd0: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
dce0: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
dcf0: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
dd00: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
dd10: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
dd20: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
dd30: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
dd40: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
dd50: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
dd60: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
dd70: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
dd80: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
dd90: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
dda0: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
ddb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
ddc0: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
ddd0: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
dde0: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
ddf0: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
de00: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
de10: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
de20: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
de30: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
de40: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
de50: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
de60: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
de70: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
de80: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
de90: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
dea0: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
deb0: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
dec0: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
ded0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
dee0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
def0: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
df00: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
df10: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
df20: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
df30: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
df40: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
df50: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
df60: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
df70: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
df80: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
df90: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
dfa0: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
dfb0: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
dfc0: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
dfd0: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
dfe0: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
dff0: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
e000: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
e010: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
e020: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
e030: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
e040: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
e050: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
e060: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
e070: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
e080: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
e090: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
e0a0: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
e0b0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
e0c0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
e0d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e0e0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
e0f0: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
e100: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
e110: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
e120: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
e130: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e140: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e150: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
e160: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(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: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
e1a0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
e1b0: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
e1c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e1d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e1e0: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
e1f0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
e200: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
e210: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e220: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
e230: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
e240: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
e250: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
e260: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
e270: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
e280: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
e290: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
e2a0: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
e2b0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
e2c0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
e2d0: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
e2e0: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
e2f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e300: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
e310: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
e320: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
e330: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
e340: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
e350: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
e360: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
e370: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
e380: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
e390: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
e3a0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
e3b0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e3c0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
e3d0: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
e3e0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
e3f0: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
e400: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
e410: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
e420: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
e430: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
e440: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e450: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e460: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
e470: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
e480: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
e490: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
e4a0: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
e4b0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
e4c0: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
e4d0: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
e4e0: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
e4f0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
e500: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
e510: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e520: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
e530: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
e540: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
e550: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
e560: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e570: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e580: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
e590: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
e5a0: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
e5b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e5c0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
e5d0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
e5e0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
e5f0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
e600: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
e610: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e620: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
e630: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
e640: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
e650: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
e660: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
e670: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
e680: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
e690: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
e6a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
e6b0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
e6c0: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
e6d0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
e6e0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
e6f0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
e700: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
e710: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
e720: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
e730: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
e740: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
e750: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
e760: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
e770: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
e780: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
e790: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
e7a0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
e7b0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
e7c0: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
e7d0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
e7e0: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
e7f0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e800: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
e810: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e820: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
e830: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
e840: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
e850: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
e860: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
e870: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
e880: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
e890: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
e8a0: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
e8b0: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
e8c0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
e8d0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
e8e0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
e8f0: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
e900: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
e910: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
e920: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
e930: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
e940: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
e950: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
e960: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
e970: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
e980: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e990: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
e9a0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
e9b0: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
e9c0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e9d0: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
e9e0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
e9f0: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
ea00: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
ea10: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
ea20: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
ea30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ea40: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
ea50: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
ea60: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ea70: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
ea80: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
ea90: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
eaa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
eab0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
eac0: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
ead0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
eae0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
eaf0: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
eb00: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
eb10: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
eb20: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
eb30: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
eb40: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
eb50: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
eb60: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
eb70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
eb80: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
eb90: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
eba0: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
ebb0: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
ebc0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
ebd0: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
ebe0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
ebf0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
ec00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
ec10: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
ec20: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
ec30: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
ec40: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
ec50: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
ec60: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
ec70: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
ec80: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
ec90: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
eca0: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
ecb0: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
ecc0: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
ecd0: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
ece0: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
ecf0: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
ed00: 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
ed10: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
ed20: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
ed30: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
ed40: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
ed50: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
ed60: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
ed70: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
ed80: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
ed90: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
eda0: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
edb0: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
edc0: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
edd0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
ede0: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
edf0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
ee00: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
ee10: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
ee20: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
ee30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ee40: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
ee50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ee60: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
ee70: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
ee80: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ee90: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
eea0: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
eeb0: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
eec0: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
eed0: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
eee0: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
eef0: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
ef00: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
ef10: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
ef20: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
ef30: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
ef40: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
ef50: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
ef60: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
ef70: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
ef80: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
ef90: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
efa0: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
efb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
efc0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
efd0: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
efe0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
eff0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
f000: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
f010: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
f020: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
f030: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
f040: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
f050: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
f060: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
f070: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
f080: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
f090: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
f0a0: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
f0b0: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
f0c0: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
f0d0: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
f0e0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
f0f0: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
f100: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
f110: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
f120: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
f130: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
f140: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
f150: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
f160: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
f170: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
f180: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f190: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
f1a0: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
f1b0: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
f1c0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
f1d0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
f1e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f1f0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
f200: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
f210: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f220: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
f230: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
f240: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
f250: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
f260: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
f270: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
f280: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
f290: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f2a0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f2b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f2c0: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
f2d0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
f2e0: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
f2f0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
f300: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
f310: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
f320: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
f330: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
f340: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
f350: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f360: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
f370: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
f380: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
f390: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
f3a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
f3b0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
f3c0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
f3d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f3e0: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
f3f0: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
f400: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f410: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
f420: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f430: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
f440: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
f450: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
f460: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
f470: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
f480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
f490: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
f4a0: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
f4b0: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
f4c0: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
f4d0: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
f4e0: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
f4f0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
f500: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
f510: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
f520: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
f530: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
f540: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f550: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
f560: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
f570: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
f580: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
f590: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
f5a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f5b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
f5c0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
f5d0: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
f5e0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
f5f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f600: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
f610: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
f620: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
f630: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
f640: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
f650: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
f660: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
f670: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
f680: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
f690: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
f6a0: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
f6b0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f6c0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
f6d0: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
f6e0: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
f6f0: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
f700: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
f710: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
f720: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
f730: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
f740: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f750: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
f760: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
f770: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
f780: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
f790: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
f7a0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f7b0: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
f7c0: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
f7d0: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
f7e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
f7f0: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
f800: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
f810: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
f820: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
f830: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
f840: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
f850: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
f860: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
f870: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
f880: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
f890: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
f8a0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
f8b0: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
f8c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
f8d0: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
f8e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
f8f0: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
f900: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
f910: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f920: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
f930: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
f940: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
f950: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
f960: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
f970: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
f980: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
f990: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
f9a0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
f9b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
f9c0: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
f9d0: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
f9e0: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
f9f0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
fa00: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
fa10: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
fa20: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
fa30: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
fa40: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
fa50: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
fa60: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
fa70: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
fa80: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
fa90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
faa0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fab0: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
fac0: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
fad0: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
fae0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
faf0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
fb00: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
fb10: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
fb20: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
fb30: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
fb40: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
fb50: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
fb60: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
fb70: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
fb80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
fb90: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
fba0: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
fbb0: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
fbc0: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
fbd0: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
fbe0: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
fbf0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
fc00: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
fc10: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
fc20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
fc30: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
fc40: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
fc50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
fc60: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
fc70: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
fc80: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
fc90: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fca0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
fcb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
fcc0: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
fcd0: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
fce0: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
fcf0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
fd00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fd10: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
fd20: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
fd30: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
fd40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fd50: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
fd60: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
fd70: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
fd80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
fd90: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
fda0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
fdb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fdc0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
fdd0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
fde0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
fdf0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
fe00: 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
fe10: 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
fe20: 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
fe30: 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
fe40: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
fe50: 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
fe60: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
fe70: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
fe80: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
fe90: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
fea0: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
feb0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
fec0: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
fed0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
fee0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
fef0: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
ff00: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
ff10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
ff20: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
ff30: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
ff40: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
ff50: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
ff60: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
ff70: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
ff80: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
ff90: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
ffa0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
ffb0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
ffc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ffd0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
ffe0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
fff0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
10000 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
10010 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10020 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
10030 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
10040 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10050 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10060 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
10070 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
10080 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10090 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
100a0 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
100b0 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
100c0 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
100d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
100e0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
100f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
10100 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
10110 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
10120 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
10130 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
10140 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
10150 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
10160 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
10170 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
10180 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
10190 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
101a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
101b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
101c0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
101d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
101e0 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
101f0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
10200 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
10210 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
10220 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
10230 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
10240 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
10250 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
10260 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
10270 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
10280 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
10290 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
102a0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
102b0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
102c0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
102d0 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
102e0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
102f0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
10300 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
10310 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
10320 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10330 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
10340 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10350 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
10360 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
10370 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
10380 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
10390 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
103a0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
103b0 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
103c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
103d0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
103e0 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
103f0 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
10400 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10410 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10420 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
10430 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
10440 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10450 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
10460 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
10470 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
10480 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
10490 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
104a0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
104b0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
104c0 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
104d0 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
104e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
104f0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
10500 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10510 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
10520 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
10530 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
10540 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
10550 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
10560 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
10570 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
10580 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
10590 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
105a0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
105b0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
105c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
105d0 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
105e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
105f0 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
10600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
10610 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
10620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10630 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
10640 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10650 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
10660 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10670 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10680 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10690 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
106a0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
106b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
106c0 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
106d0 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
106e0 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
106f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10700 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
10710 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10720 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
10730 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10740 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
10750 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
10760 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10770 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10780 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10790 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
107a0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
107b0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
107c0 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
107d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
107e0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
107f0 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10800 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10810 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
10820 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
10830 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
10840 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
10850 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10860 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10870 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10880 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10890 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
108a0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
108b0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
108c0 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
108d0 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
108e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
108f0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10900 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
10910 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10920 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
10930 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
10940 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
10950 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
10960 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10970 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10980 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10990 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
109a0 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
109b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
109c0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
109d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
109e0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
109f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10a00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10a10 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
10a20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10a30 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
10a40 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
10a50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10a60 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10a70 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10a80 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10a90 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10aa0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10ab0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10ad0 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10af0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10b00 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
10b10 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10b20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
10b30 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
10b40 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
10b50 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
10b60 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10b70 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10b80 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10b90 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10ba0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10bb0 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
10bc0 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
10bd0 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10be0 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10bf0 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10c00 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
10c10 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
10c20 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
10c30 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
10c40 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
10c50 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
10c60 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10c70 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10c80 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
10c90 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
10ca0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
10cb0 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
10cc0 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
10cd0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10ce0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10cf0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10d00 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
10d10 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
10d20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
10d30 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
10d40 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
10d50 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
10d60 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10d70 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
10d80 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
10d90 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
10da0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
10db0 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
10dc0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
10dd0 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10de0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10df0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10e00 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
10e10 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
10e20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
10e30 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
10e40 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
10e50 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
10e60 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10e70 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
10e80 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
10e90 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
10ea0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10eb0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
10ec0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
10ed0 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10ee0 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10ef0 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10f00 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10f10 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10f20 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10f30 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10f40 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10f50 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10f60 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10f70 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10f80 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
10f90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
10fa0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
10fb0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
10fc0 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
10fd0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10fe0 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10ff0 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
11000 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
11010 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
11020 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
11030 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
11040 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
11050 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
11060 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
11070 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
11080 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
11090 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
110a0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
110b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
110c0 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
110d0 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
110e0 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
110f0 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
11100 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
11110 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
11120 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
11130 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
11140 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
11150 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11160 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
11170 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
11180 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
11190 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
111a0 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
111b0 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
111c0 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
111d0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
111e0 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
111f0 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
11200 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11210 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
11220 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
11230 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
11240 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
11250 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
11260 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
11270 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
11280 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
11290 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
112a0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
112b0 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
112c0 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
112d0 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
112e0 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
112f0 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
11300 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
11310 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
11320 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
11330 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11340 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
11350 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
11360 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
11370 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
11380 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
11390 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
113a0 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
113b0 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
113c0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
113d0 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
113e0 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
113f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
11400 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
11410 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11420 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
11430 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
11440 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
11450 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
11460 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11470 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
11480 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
114a0 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
114b0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
114c0 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
114d0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
114e0 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
114f0 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11500 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
11510 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
11520 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
11530 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
11540 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
11550 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
11560 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11570 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11580 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11590 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
115a0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
115b0 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
115c0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
115d0 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
115e0 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
115f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11600 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
11610 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
11620 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
11630 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
11640 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
11650 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
11660 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11670 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11680 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11690 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
116a0 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
116b0 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
116c0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
116d0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
116e0 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
116f0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11700 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
11710 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
11720 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
11730 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
11740 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11750 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
11760 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11770 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11780 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11790 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
117a0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
117b0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
117c0 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
117d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
117e0 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
117f0 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11800 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
11810 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11820 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
11830 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
11840 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11850 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
11860 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11870 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11880 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11890 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
118a0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
118b0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
118c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
118d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
118e0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
118f0 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11900 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
11910 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
11920 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
11930 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
11940 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
11950 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
11960 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11970 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11980 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11990 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
119a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
119b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
119c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
119d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
119e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
119f0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11a00 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
11a10 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11a20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
11a30 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
11a40 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
11a50 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
11a60 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11a70 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11a80 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11a90 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11aa0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11ab0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11ac0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11ad0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11ae0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11af0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11b00 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11b10 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
11b20 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
11b30 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
11b40 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11b50 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
11b60 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
11b70 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
11b80 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
11b90 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
11ba0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11bb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11bc0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11bd0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11be0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11bf0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11c00 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11c10 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11c20 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
11c30 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
11c40 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
11c50 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
11c60 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
11c70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11c80 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
11c90 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
11ca0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11cb0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
11cc0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
11cd0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11ce0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11cf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11d00 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
11d10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11d20 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
11d30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11d40 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11d50 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11d60 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11d70 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11d80 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11d90 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
11da0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11db0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
11dc0 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
11dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11de0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11df0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11e00 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
11e10 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
11e20 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
11e30 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
11e40 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11e50 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11e60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11e70 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
11e80 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
11e90 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
11ea0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
11eb0 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
11ec0 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
11ed0 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
11ee0 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
11ef0 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
11f00 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
11f10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f20 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
11f30 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
11f40 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11f50 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11f60 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11f70 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11f80 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11f90 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11fa0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11fb0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11fc0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
11fd0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
11fe0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
11ff0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12000 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12010 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12020 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12030 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12040 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
12050 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12060 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12070 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
12080 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12090 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
120a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
120b0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
120c0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
120d0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
120e0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
120f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12100 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
12110 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
12120 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
12130 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
12140 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
12150 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
12160 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
12170 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
12180 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12190 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
121a0 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
121b0 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
121c0 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
121d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
121e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
121f0 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
12200 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12210 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
12220 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
12230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12240 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
12250 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
12260 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
12270 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
12280 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
12290 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
122a0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
122b0 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
122c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
122d0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
122e0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
122f0 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
12300 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12310 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12320 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12330 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12340 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12350 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12360 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
12370 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
12380 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
12390 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
123a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
123b0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
123c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
123d0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
123e0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
123f0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
12400 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12410 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12420 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12430 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12440 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12450 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
12460 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
12470 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
12480 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12490 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
124a0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
124b0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
124c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
124d0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
124e0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
124f0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12500 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12510 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12520 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12530 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
12540 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
12550 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12560 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
12570 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12580 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12590 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
125a0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
125b0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
125c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
125d0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
125e0 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
125f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12600 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
12610 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12620 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12630 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12640 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12650 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12660 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12670 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
12680 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12690 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
126a0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
126b0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
126c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
126d0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
126e0 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
126f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12700 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12710 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12720 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12730 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
12740 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12750 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12760 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12770 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12780 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12790 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
127a0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
127b0 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
127c0 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
127d0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
127e0 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
127f0 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12800 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12810 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12820 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12830 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12840 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
12850 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12870 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
12880 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12890 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
128a0 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
128b0 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
128c0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
128d0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
128e0 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
128f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12900 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
12910 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12920 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12930 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
12940 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
12950 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
12960 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
12970 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
12980 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12990 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
129a0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
129b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
129c0 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
129d0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
129e0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
129f0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12a00 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
12a10 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
12a20 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
12a30 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12a40 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
12a50 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
12a60 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
12a70 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
12a80 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
12a90 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
12aa0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
12ab0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12ac0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
12ad0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
12ae0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12af0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12b00 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
12b10 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
12b20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12b30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12b40 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
12b50 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12b60 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
12b70 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
12b80 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
12b90 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
12ba0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12bb0 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
12bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12bd0 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
12be0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12bf0 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12c00 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12c10 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12c20 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12c30 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
12c40 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
12c50 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
12c60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12c70 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12c80 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12c90 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
12ca0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12cb0 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
12cc0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
12cd0 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
12ce0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12cf0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12d00 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12d10 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
12d20 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
12d30 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
12d40 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
12d50 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
12d60 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
12d70 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
12d80 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
12d90 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12da0 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
12db0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12dc0 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12dd0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12de0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12df0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12e00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12e10 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
12e20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12e30 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
12e40 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
12e50 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
12e60 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
12e70 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
12e80 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
12e90 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
12ea0 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
12eb0 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
12ec0 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
12ed0 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
12ee0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
12ef0 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
12f00 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
12f10 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
12f20 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
12f30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12f40 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
12f50 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
12f60 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
12f70 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
12f80 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
12f90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12fa0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
12fb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12fc0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
12fd0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
12fe0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12ff0 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
13000 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13010 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
13020 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13030 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
13040 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
13050 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
13060 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13070 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
13080 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13090 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
130a0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
130b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
130c0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
130d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
130e0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
130f0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
13100 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f  G_PCACHE2].** co
13110 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13120 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  on..** ^There ar
13130 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13140 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13150 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
13160 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
13170 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
13180 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
13190 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
131a0 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
131b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
131c0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
131d0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
131e0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
131f0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
13200 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
13210 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
13220 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35  tween 512 and 65
13230 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  536) plus some e
13240 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
13250 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
13260 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
13270 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
13280 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
13290 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
132a0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
132b0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
132c0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
132d0 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a  DRSZ] option .**
132e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
132f0 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69  fig()]..** ^It i
13300 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
13310 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
13320 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
13330 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
13340 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
13350 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
13360 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
13370 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
13380 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13390 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  e aligned block 
133a0 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a  of memory that.*
133b0 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a  * is at least sz
133c0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
133d0 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75  ry, otherwise su
133e0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
133f0 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
13400 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13410 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
13420 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
13430 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13440 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
13450 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
13460 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
13470 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
13480 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
13490 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
134a0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
134b0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
134c0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
134d0 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
134e0 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
134f0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
13500 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
13510 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
13520 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c   storage space.<
13530 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13540 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
13550 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13560 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
13570 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13580 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
13590 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
135a0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
135b0 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
135c0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
135d0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
135e0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
135f0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
13600 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
13610 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
13620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13630 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51  ATCH] and.** [SQ
13640 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13650 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
13660 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13670 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
13680 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
13690 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
136a0 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
136b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
136c0 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
136d0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
136e0 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
136f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
13700 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
13710 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
13720 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13730 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
13740 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
13750 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
13760 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
13770 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
13780 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
13790 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
137a0 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
137b0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
137c0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
137d0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
137e0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
137f0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
13800 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
13810 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
13820 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
13830 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
13840 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
13850 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
13860 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
13870 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
13880 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
13890 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
138a0 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
138b0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
138c0 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
138d0 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
138e0 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
138f0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
13900 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
13910 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13920 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
13930 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13940 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
13950 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
13960 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
13970 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
13980 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13990 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
139a0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
139b0 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
139c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
139d0 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
139e0 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
139f0 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
13a00 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13a10 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
13a20 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
13a30 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13a40 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
13a50 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13a60 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
13a70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13a80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13a90 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13aa0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13ab0 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
13ac0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13ad0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13ae0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13af0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13b00 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
13b10 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
13b20 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13b30 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
13b40 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
13b50 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
13b60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13b70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
13b80 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13b90 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
13ba0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13bb0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13bc0 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13bd0 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13be0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13bf0 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13c00 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13c10 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13c20 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13c30 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13c40 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13c50 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13c60 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13c70 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13c80 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13c90 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13ca0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13cb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13cc0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13cd0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13ce0 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13cf0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13d00 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13d10 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13d20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13d30 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
13d40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13d50 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
13d60 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13d70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13d80 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13d90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13da0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
13db0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13dc0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13de0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13df0 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
13e00 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13e10 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
13e20 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
13e30 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
13e40 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
13e50 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
13e60 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
13e70 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
13e80 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
13e90 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13ea0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13eb0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
13ec0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
13ed0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
13ee0 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
13ef0 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
13f00 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
13f10 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13f20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13f30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13f40 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13f50 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13f60 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13f70 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13f80 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13f90 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13fa0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
13fb0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
13fc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13fd0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
13fe0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13ff0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
14000 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
14010 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14020 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
14030 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14040 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
14050 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14060 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
14070 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14090 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
140a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
140b0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
140c0 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
140d0 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
140e0 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
140f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14100 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
14110 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
14120 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
14130 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
14140 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
14150 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
14160 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
14170 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
14180 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14190 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
141a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
141b0 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
141c0 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
141d0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
141e0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
141f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
14200 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
14210 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14220 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
14230 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
14240 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
14250 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
14260 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
14270 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
14280 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14290 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
142a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
142b0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
142c0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
142d0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
142e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
142f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14300 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
14310 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
14320 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14330 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
14340 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
14350 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
14360 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
14370 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
14380 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
14390 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
143a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
143b0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
143c0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
143d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
143e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
143f0 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14400 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14410 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14420 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14430 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
14440 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14450 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14460 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
14470 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
14480 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14490 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
144a0 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
144b0 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
144c0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
144d0 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
144e0 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
144f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14500 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
14510 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14520 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
14530 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
14540 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
14550 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
14560 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
14570 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
14580 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
14590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
145a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
145b0 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
145c0 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
145d0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
145e0 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
145f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
14600 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
14610 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
14620 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
14630 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
14640 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
14650 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
14660 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
14670 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
14680 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
14690 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
146a0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
146b0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
146c0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
146d0 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
146e0 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
146f0 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
14700 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
14710 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
14720 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
14730 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
14740 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
14750 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
14760 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14770 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14780 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
14790 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
147a0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
147b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
147c0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
147d0 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
147e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
147f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14800 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
14810 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
14820 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
14830 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
14840 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
14850 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
14860 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
14870 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
14880 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
14890 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
148a0 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
148b0 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
148c0 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
148d0 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
148e0 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
148f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
14900 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
14910 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
14920 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
14930 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
14940 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
14950 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
14960 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
14970 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
14980 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
14990 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
149a0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
149b0 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
149c0 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
149d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
149e0 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
149f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
14a00 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
14a10 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
14a20 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14a30 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14a40 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
14a50 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
14a60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14a70 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
14a80 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
14a90 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
14aa0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
14ab0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14ac0 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
14ad0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14ae0 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
14af0 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
14b00 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
14b10 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
14b20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
14b30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
14b40 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
14b50 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
14b60 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
14b70 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
14b80 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
14b90 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
14ba0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
14bb0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
14bc0 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
14bd0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14be0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
14bf0 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
14c00 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14c10 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
14c20 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
14c30 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14c40 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
14c50 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
14c60 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
14c70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14c80 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14c90 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
14ca0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14cb0 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
14cc0 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
14cd0 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
14ce0 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
14cf0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
14d00 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
14d10 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
14d20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14d30 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14d40 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
14d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14d60 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14d70 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
14d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14d90 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
14da0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14db0 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
14dc0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14dd0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
14de0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
14df0 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
14e00 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
14e10 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
14e20 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
14e30 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
14e40 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
14e50 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
14e60 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
14e70 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
14e80 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
14e90 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
14ea0 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
14eb0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
14ec0 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
14ed0 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
14ee0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
14ef0 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
14f00 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
14f10 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
14f20 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
14f30 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
14f40 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
14f50 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
14f60 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
14f70 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
14f80 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
14f90 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
14fa0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
14fb0 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
14fc0 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
14fd0 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
14fe0 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
14ff0 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
15000 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
15010 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
15020 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
15030 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
15040 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
15050 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15060 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
15070 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15080 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
15090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
150a0 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
150b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
150c0 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
150d0 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
150e0 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
150f0 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
15100 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
15110 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
15120 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
15130 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
15140 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
15150 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15160 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15170 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15180 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
15190 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
151a0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
151b0 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
151c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
151d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
151e0 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
151f0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15200 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
15210 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
15220 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
15230 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
15240 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
15250 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
15260 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
15270 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
15280 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
15290 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
152a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
152b0 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
152c0 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
152d0 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
152e0 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
152f0 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
15300 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
15310 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15320 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
15330 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
15340 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
15350 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15360 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
15370 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
15380 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
15390 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
153a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
153b0 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
153c0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
153d0 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
153e0 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
153f0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15400 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
15410 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
15420 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
15430 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
15440 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
15450 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
15460 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
15470 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15480 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
15490 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
154a0 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
154b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
154c0 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
154d0 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
154e0 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
154f0 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
15500 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
15510 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
15520 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
15530 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
15540 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
15550 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
15560 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
15570 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
15580 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
15590 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
155a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
155b0 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
155c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
155d0 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
155e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
155f0 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
15600 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
15610 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
15620 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
15630 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
15640 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
15650 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
15660 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
15670 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
15680 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
15690 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
156a0 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
156b0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
156c0 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
156d0 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
156e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
156f0 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
15700 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
15710 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
15720 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
15730 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
15740 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
15750 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
15760 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
15770 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
15780 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
15790 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
157a0 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
157b0 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
157c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
157d0 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
157e0 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
157f0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
15800 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
15810 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
15820 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
15830 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
15840 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
15850 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
15860 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
15870 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
15880 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
15890 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
158a0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
158b0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
158c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
158d0 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
158e0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
158f0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15900 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
15910 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
15920 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
15930 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
15940 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
15950 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
15960 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15970 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
15980 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
15990 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
159a0 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
159b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
159c0 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
159d0 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
159e0 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
159f0 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a  reated heap..**.
15a00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15a10 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
15a20 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15a30 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
15a40 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
15a50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15a60 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
15a70 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15a80 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
15a90 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15aa0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
15ab0 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
15ac0 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
15ad0 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
15ae0 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
15af0 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
15b00 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
15b10 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15b20 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
15b30 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
15b40 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
15b50 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
15b60 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
15b70 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
15b80 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
15b90 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
15ba0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15bb0 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
15bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15bd0 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
15be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15bf0 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
15c00 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
15c10 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
15c20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
15c30 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
15c40 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
15c50 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
15c60 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
15c70 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
15c80 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
15c90 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
15ca0 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
15cb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
15cc0 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
15cd0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
15ce0 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
15cf0 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
15d00 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
15d10 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
15d20 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
15d30 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
15d40 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
15d50 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
15d60 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
15d70 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
15d80 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
15d90 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
15da0 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
15db0 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
15dc0 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
15dd0 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
15de0 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
15df0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
15e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15e10 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
15e20 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15e30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15e40 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
15e50 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
15e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15e70 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
15e80 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
15e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15ea0 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
15eb0 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
15ec0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
15ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15ee0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
15ef0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
15f00 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
15f10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15f20 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
15f30 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
15f40 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15f50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15f60 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15f70 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
15f80 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
15f90 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
15fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15fb0 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
15fc0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
15fd0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
15fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15ff0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
16000 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
16010 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16020 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
16030 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
16040 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16050 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16070 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
16080 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16090 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
160a0 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
160b0 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
160c0 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
160d0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
160e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
160f0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16100 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16110 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16120 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
16130 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
16140 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16150 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16160 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
16170 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
16180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16190 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
161a0 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
161b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
161c0 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
161d0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
161e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
161f0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16200 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
16210 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
16220 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
16230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16240 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
16250 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
16260 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
16270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16280 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16290 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
162a0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
162b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
162c0 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
162d0 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
162e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
162f0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16300 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
16310 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
16320 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
16330 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16340 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16350 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
16360 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
16370 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16380 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
16390 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
163a0 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
163b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
163c0 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
163d0 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
163e0 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a  d int szPma */..
163f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16400 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
16410 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
16420 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
16430 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
16440 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
16450 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
16460 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
16470 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
16480 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
16490 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
164a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
164b0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
164c0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
164d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
164e0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
164f0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
16500 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
16510 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
16520 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16530 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
16540 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
16550 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
16560 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
16570 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
16580 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16590 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
165a0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
165b0 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
165c0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
165d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
165e0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
165f0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
16600 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
16610 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
16620 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
16630 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
16640 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
16650 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
16660 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16670 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
16680 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16690 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
166a0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
166b0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
166c0 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
166d0 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
166e0 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
166f0 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
16700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16710 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
16720 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
16730 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
16740 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
16750 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
16760 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
16770 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
16780 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
16790 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
167a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
167b0 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
167c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
167d0 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
167e0 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
167f0 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
16800 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
16810 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16820 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
16830 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16840 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
16850 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
16860 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
16870 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
16880 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
16890 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
168a0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
168b0 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
168c0 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
168d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
168e0 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
168f0 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
16900 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
16910 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
16920 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
16930 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
16940 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
16950 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
16960 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
16970 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16980 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
16990 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
169a0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
169b0 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
169c0 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
169d0 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
169e0 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
169f0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
16a00 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
16a10 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
16a20 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
16a30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16a40 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
16a50 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
16a60 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
16a70 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
16a80 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
16a90 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
16aa0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
16ab0 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
16ac0 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
16ad0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
16ae0 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
16af0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16b00 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
16b10 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
16b20 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
16b30 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16b40 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
16b50 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
16b60 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
16b70 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
16b80 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
16b90 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
16ba0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
16bb0 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
16bc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16bd0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16be0 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
16bf0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16c00 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16c10 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
16c20 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
16c30 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
16c40 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
16c50 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
16c60 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
16c70 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
16c80 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
16c90 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
16ca0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
16cb0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
16cc0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16cd0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16ce0 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
16cf0 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
16d00 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
16d10 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
16d20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
16d30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
16d40 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
16d50 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
16d60 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
16d70 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
16d80 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
16d90 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
16da0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16dc0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16dd0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16de0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16df0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16e00 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
16e10 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16e20 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
16e30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16e40 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
16e50 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
16e60 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16e70 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16e80 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
16e90 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
16ea0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
16eb0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16ec0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16ed0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16ee0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16ef0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16f00 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
16f10 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16f20 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
16f30 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16f40 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
16f50 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
16f60 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16f70 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
16f80 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16f90 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
16fa0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16fb0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16fc0 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
16fd0 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
16fe0 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
16ff0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17000 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17010 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17020 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17030 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
17040 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
17050 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17060 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17070 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
17080 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17090 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
170a0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
170b0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
170c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
170d0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
170e0 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
170f0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
17100 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
17110 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
17120 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
17130 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
17140 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
17150 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
17160 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
17170 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
17180 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
17190 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
171a0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
171b0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
171c0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
171d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
171e0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
171f0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
17200 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
17210 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
17220 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
17230 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
17240 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
17250 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
17260 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
17270 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
17280 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
17290 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
172a0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
172b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
172c0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
172d0 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
172e0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
172f0 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
17300 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
17310 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
17320 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
17330 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
17340 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
17350 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
17360 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
17370 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
17380 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
17390 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
173a0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
173b0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
173c0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
173d0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
173e0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
173f0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
17400 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
17410 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
17420 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
17430 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
17440 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
17450 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
17460 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
17470 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
17480 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17490 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  D) interface ret
174a0 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
174b0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74   of the .** most
174c0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
174d0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
174e0 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
174f0 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
17500 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
17510 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
17520 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  * ^Inserts into 
17530 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
17540 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72  tables are not r
17550 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  ecorded..** ^If 
17560 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
17570 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
17580 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76  id tables.** hav
17590 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
175a0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
175b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a  connection D, .*
175c0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  * then sqlite3_l
175d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
175e0 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (D) returns zero
175f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
17600 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
17610 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
17620 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
17630 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
17640 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
17650 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
17660 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
17670 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
17680 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
17690 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
176a0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
176b0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
176c0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
176d0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
176e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
176f0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
17700 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
17710 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
17720 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
17730 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
17740 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17750 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
17760 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
17770 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
17780 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
17790 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
177a0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
177b0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
177c0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
177d0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
177e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
177f0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
17800 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
17810 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
17820 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
17830 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
17840 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
17850 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
17860 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
17870 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
17880 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
17890 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
178a0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
178b0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
178c0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
178d0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
178e0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
178f0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
17900 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
17910 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
17920 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
17930 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
17940 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
17950 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
17960 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
17970 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
17980 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
17990 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
179a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
179b0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
179c0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
179d0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
179e0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
179f0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
17a00 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
17a10 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
17a20 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
17a30 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
17a40 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
17a50 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
17a60 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
17a70 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17a80 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
17a90 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17aa0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
17ab0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
17ac0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
17ad0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
17ae0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
17af0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
17b00 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
17b10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
17b20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
17b30 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
17b40 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
17b50 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
17b60 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
17b70 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
17b80 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
17b90 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
17ba0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
17bb0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
17bc0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
17bd0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
17be0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
17bf0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
17c00 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17c10 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
17c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
17c30 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
17c40 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17c50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
17c60 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
17c70 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
17c80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
17c90 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
17ca0 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
17cb0 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
17cc0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17cd0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17ce0 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
17cf0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
17d00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17d10 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
17d20 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
17d30 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
17d40 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
17d50 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
17d60 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
17d70 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
17d80 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
17d90 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
17da0 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
17db0 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
17dc0 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
17dd0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
17de0 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
17df0 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
17e00 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
17e10 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
17e20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17e30 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
17e40 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
17e50 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
17e60 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
17e70 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
17e80 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
17e90 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
17ea0 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
17eb0 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
17ec0 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
17ed0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17ee0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
17ef0 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
17f00 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
17f10 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17f20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
17f30 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
17f40 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
17f50 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
17f60 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
17f70 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
17f80 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
17f90 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
17fa0 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
17fb0 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
17fc0 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
17fd0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
17fe0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
17ff0 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
18000 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
18010 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
18020 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
18030 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
18040 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
18050 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18060 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
18070 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
18080 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
18090 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
180a0 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
180b0 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
180c0 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
180d0 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
180e0 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
180f0 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
18100 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
18110 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
18120 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
18130 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
18140 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
18150 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
18160 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
18170 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
18180 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
18190 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
181a0 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
181b0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
181c0 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
181d0 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
181e0 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
181f0 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
18200 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
18210 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
18220 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
18230 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
18240 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
18250 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
18260 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
18270 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
18280 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
18290 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
182a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
182b0 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
182c0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
182d0 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
182e0 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
182f0 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
18300 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
18310 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
18320 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
18330 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18340 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
18350 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
18360 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
18370 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
18380 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18390 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
183a0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
183b0 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
183c0 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
183d0 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
183e0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
183f0 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
18400 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
18410 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
18420 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
18430 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
18440 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
18450 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
18460 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
18470 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
18480 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
18490 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
184a0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
184b0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
184c0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
184d0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
184e0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
184f0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18500 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
18510 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
18520 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
18530 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18540 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
18550 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18560 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18570 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
18580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18590 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
185a0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
185b0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
185c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
185d0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
185e0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
185f0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
18600 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
18610 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18620 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
18630 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
18640 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
18650 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
18660 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
18670 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
18680 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
18690 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
186a0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
186b0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
186c0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
186d0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
186e0 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
186f0 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
18700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
18710 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
18720 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
18730 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
18740 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
18750 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
18760 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
18770 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
18780 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
18790 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
187a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
187b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
187c0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
187d0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
187e0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
187f0 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
18800 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
18810 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
18820 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
18830 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
18840 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
18850 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
18860 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
18870 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
18880 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
18890 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
188a0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
188b0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
188c0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
188d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
188e0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
188f0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
18900 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
18910 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18920 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
18930 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18940 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18950 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
18960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18970 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
18980 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18990 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
189a0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
189b0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
189c0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
189d0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
189e0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
189f0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
18a00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18a10 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
18a20 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
18a30 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ery.** METHOD: s
18a40 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18a50 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
18a60 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
18a70 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18a80 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
18a90 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
18aa0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
18ab0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
18ac0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
18ad0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
18ae0 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
18af0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
18b00 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
18b10 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
18b20 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
18b30 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
18b40 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
18b50 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
18b60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
18b70 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
18b80 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
18b90 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
18ba0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
18bb0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
18bc0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
18bd0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
18be0 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
18bf0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
18c00 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
18c10 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
18c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
18c30 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
18c40 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
18c50 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
18c60 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
18c70 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
18c80 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
18c90 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
18ca0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
18cb0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
18cc0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
18cd0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
18ce0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
18cf0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
18d00 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
18d10 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
18d20 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
18d30 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
18d40 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
18d50 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
18d60 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
18d70 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
18d80 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
18d90 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
18da0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
18db0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
18dc0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
18dd0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
18de0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
18df0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
18e00 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
18e10 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
18e20 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
18e30 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
18e40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18e50 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
18e60 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
18e70 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
18e80 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
18e90 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
18ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
18eb0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
18ec0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
18ed0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
18ee0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18ef0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18f00 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
18f10 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
18f20 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
18f30 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
18f40 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
18f50 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
18f60 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
18f70 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
18f80 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18f90 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
18fa0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
18fb0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
18fc0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
18fd0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
18fe0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
18ff0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
19000 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
19010 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
19020 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
19030 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
19040 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
19050 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
19060 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
19070 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
19080 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
19090 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
190a0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
190b0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
190c0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
190d0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
190e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
190f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19100 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
19110 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
19120 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
19130 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
19140 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
19150 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
19160 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
19170 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
19180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19190 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
191a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
191b0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
191c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
191d0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
191e0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
191f0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
19200 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
19210 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
19220 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
19230 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
19240 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
19250 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
19260 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
19270 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
19280 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
19290 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
192a0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
192b0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
192c0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
192d0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
192e0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
192f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
19300 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
19310 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
19320 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
19330 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
19340 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
19350 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
19360 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
19370 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
19380 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
19390 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
193a0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
193b0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
193c0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
193d0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
193e0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
193f0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
19400 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
19410 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
19420 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
19430 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
19440 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
19450 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
19460 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
19470 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
19480 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
19490 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
194a0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
194b0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
194c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
194d0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
194e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
194f0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
19500 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
19510 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
19520 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
19530 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
19540 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
19550 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
19560 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19570 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
19580 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
19590 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
195a0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
195b0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
195c0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
195d0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
195e0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
195f0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
19600 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
19610 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
19620 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
19630 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
19640 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
19650 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
19660 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
19670 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
19680 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
19690 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
196a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
196b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
196c0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
196d0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
196e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
196f0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
19700 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
19710 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19720 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
19730 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
19740 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
19750 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
19760 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
19770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
19780 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
19790 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
197a0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
197b0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
197c0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
197d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
197e0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
197f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
19800 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
19810 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
19820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
19830 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
19840 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
19850 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
19860 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
19870 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
19880 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
19890 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
198a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
198b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
198c0 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
198d0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
198e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
198f0 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
19900 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
19910 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
19920 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
19930 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
19940 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
19950 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
19960 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
19970 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
19980 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
19990 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
199a0 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
199b0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
199c0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
199d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
199e0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
199f0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
19a00 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
19a10 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
19a20 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
19a30 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19a40 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
19a50 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
19a60 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
19a70 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
19a80 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
19a90 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
19aa0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
19ab0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
19ac0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
19ad0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
19ae0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
19af0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
19b00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19b10 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
19b20 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
19b30 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
19b40 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
19b50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
19b60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
19b70 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
19b80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
19b90 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
19ba0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
19bb0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
19bc0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
19bd0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19be0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
19bf0 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
19c00 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
19c10 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
19c20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
19c30 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
19c40 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
19c50 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
19c60 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
19c70 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
19c80 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
19c90 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
19ca0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
19cb0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
19cc0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19cd0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
19ce0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
19cf0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
19d00 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
19d10 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
19d20 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
19d30 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
19d40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
19d50 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
19d60 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
19d70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
19d80 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
19d90 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
19da0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
19db0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
19dc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
19dd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
19de0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
19df0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
19e00 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
19e10 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
19e20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
19e30 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
19e40 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
19e50 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
19e60 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
19e70 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
19e80 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
19e90 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
19ea0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
19eb0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
19ec0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
19ed0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
19ee0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
19ef0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
19f00 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
19f10 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
19f20 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
19f30 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
19f40 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
19f50 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
19f60 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
19f70 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
19f80 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19f90 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
19fa0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
19fb0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19fc0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
19fd0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
19fe0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
19ff0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1a000 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1a010 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1a020 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1a030 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1a040 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1a050 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1a060 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1a070 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1a080 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1a090 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1a0a0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1a0b0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1a0c0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1a0d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1a0e0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1a0f0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1a100 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1a110 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1a120 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1a130 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1a140 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1a150 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1a160 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1a170 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1a180 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1a190 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1a1a0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1a1b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1a1c0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1a1d0 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1a1e0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1a1f0 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1a200 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1a210 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1a220 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1a230 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1a240 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1a250 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1a260 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1a270 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1a280 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1a290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1a2a0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1a2b0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1a2c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1a2d0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1a2e0 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1a2f0 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1a300 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1a310 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1a320 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1a330 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1a340 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1a350 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a360 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1a370 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1a380 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1a390 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a3a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1a3b0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1a3c0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
1a3d0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
1a3e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a3f0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1a400 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1a410 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a420 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1a430 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1a440 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1a450 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1a460 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1a470 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1a480 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1a490 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1a4a0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1a4b0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1a4c0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1a4d0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1a4e0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1a4f0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1a500 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1a510 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1a520 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1a530 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1a540 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1a550 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1a560 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a570 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1a580 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1a590 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1a5a0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1a5b0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1a5c0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1a5d0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1a5e0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1a5f0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1a600 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1a610 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1a620 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1a630 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1a640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a650 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1a660 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1a670 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1a680 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1a690 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1a6a0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1a6b0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1a6c0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1a6d0 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1a6e0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1a6f0 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1a700 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1a710 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1a720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1a730 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1a740 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1a750 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1a760 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1a770 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1a780 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ueries.** METHOD
1a790 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1a7a0 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1a7b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1a7c0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1a7d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1a7e0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1a7f0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1a800 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1a810 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1a820 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1a830 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1a840 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1a850 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1a860 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1a870 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1a880 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1a890 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1a8a0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1a8b0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1a8c0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1a8d0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1a8e0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1a8f0 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1a900 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1a910 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1a920 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1a930 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1a940 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1a950 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1a960 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1a970 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1a980 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1a990 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a9a0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1a9b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1a9c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1a9d0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1a9e0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1a9f0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1aa00 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1aa10 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1aa20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1aa30 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1aa40 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1aa50 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1aa60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1aa70 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1aa80 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1aa90 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1aaa0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1aab0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1aac0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1aad0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1aae0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1aaf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1ab00 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1ab10 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1ab20 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1ab30 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1ab40 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1ab50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1ab60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1ab70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1ab80 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1ab90 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1aba0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1abb0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1abc0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1abd0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1abe0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1abf0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ac00 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1ac10 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1ac20 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1ac30 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1ac40 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1ac50 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1ac60 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1ac70 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1ac80 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1ac90 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1aca0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1acb0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1acc0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1acd0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1ace0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1acf0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1ad00 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1ad10 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1ad20 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1ad30 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1ad40 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1ad50 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ad60 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1ad70 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1ad80 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1ad90 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1ada0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1adb0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1adc0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1add0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1ade0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1adf0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1ae00 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1ae10 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1ae20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1ae30 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ae40 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ae50 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1ae60 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1ae70 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1ae80 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1ae90 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1aea0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1aeb0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1aec0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1aed0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1aee0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1aef0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1af00 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1af10 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1af20 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1af30 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1af40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1af50 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1af60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1af70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1af80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1af90 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1afa0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1afb0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1afc0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1afd0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1afe0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1aff0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1b000 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1b010 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1b020 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1b030 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1b040 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1b050 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1b060 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1b070 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1b080 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1b090 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1b0a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1b0b0 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1b0c0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1b0d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1b0e0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1b0f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1b100 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1b110 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1b120 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1b130 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1b140 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b150 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1b160 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1b170 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1b180 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1b190 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1b1a0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1b1b0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1b1c0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1b1d0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1b1e0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1b1f0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1b200 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1b210 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1b220 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b230 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1b240 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1b250 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1b260 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1b270 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1b280 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1b290 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1b2a0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1b2b0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1b2c0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1b2d0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1b2e0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1b2f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1b300 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1b310 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1b320 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1b330 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1b340 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1b350 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1b360 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b370 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1b380 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1b390 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1b3a0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1b3b0 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1b3c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1b3d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
1b3e0 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1b3f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1b400 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1b410 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1b420 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1b430 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1b440 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1b450 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1b460 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1b470 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1b480 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1b490 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1b4a0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1b4b0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1b4c0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1b4d0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1b4e0 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1b4f0 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1b500 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1b510 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1b520 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1b530 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
1b540 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b550 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1b560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b570 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1b580 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1b590 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1b5a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1b5b0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1b5c0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1b5d0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1b5e0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1b5f0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1b600 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1b610 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1b620 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1b630 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e  on K&R formattin
1b640 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c  g options,.** pl
1b650 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1b660 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1b670 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65  formats, detaile
1b680 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65  d below..** Note
1b690 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68   that some of th
1b6a0 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66  e more obscure f
1b6b0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1b6c0 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a  s from recent.**
1b6d0 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64   C-library stand
1b6e0 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64  ards are omitted
1b6f0 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65   from this imple
1b700 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  mentation..**.**
1b710 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1b720 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1b730 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1b740 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1b750 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1b760 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1b770 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1b780 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1b790 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1b7a0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1b7b0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1b7c0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1b7d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1b7e0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1b7f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1b800 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1b810 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1b820 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1b830 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1b840 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1b850 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1b860 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1b870 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1b880 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b890 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1b8a0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1b8b0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1b8c0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1b8d0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1b8e0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1b8f0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1b900 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1b910 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1b920 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1b930 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1b940 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1b950 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1b960 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1b970 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1b980 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1b990 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1b9a0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1b9b0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1b9c0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1b9d0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1b9e0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1b9f0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1ba00 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1ba10 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ba20 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1ba30 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1ba40 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1ba50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1ba60 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1ba70 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1ba80 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1ba90 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1baa0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1bab0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1bac0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1bad0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1bae0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1baf0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1bb00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1bb10 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1bb20 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1bb30 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1bb40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1bb50 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1bb60 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1bb70 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1bb80 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1bb90 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1bba0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1bbb0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1bbc0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1bbd0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1bbe0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1bbf0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1bc00 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1bc10 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1bc20 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1bc30 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1bc40 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1bc50 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1bc60 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1bc70 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1bc80 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1bc90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bca0 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1bcb0 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1bcc0 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1bcd0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1bce0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1bcf0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1bd00 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1bd10 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1bd20 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1bd30 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1bd40 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1bd50 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1bd60 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1bd70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1bd80 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1bd90 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1bda0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1bdb0 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22  "%q", "%Q", "%w"
1bdc0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1bdd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1bde0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1bdf0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1be00 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1be10 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1be20 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1be30 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1be40 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1be50 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1be60 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1be70 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1be80 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1be90 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1bea0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1beb0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1bec0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1bed0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1bee0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1bef0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1bf00 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1bf10 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1bf20 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1bf30 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1bf40 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1bf50 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1bf60 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1bf70 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1bf80 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1bf90 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1bfa0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bfb0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1bfc0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1bfd0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1bfe0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1bff0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c000 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1c010 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1c020 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1c030 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1c040 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1c050 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1c060 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1c070 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1c080 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1c090 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c0a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1c0b0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1c0c0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1c0d0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1c0e0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1c0f0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1c100 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1c110 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1c120 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c130 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1c140 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1c150 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1c160 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1c170 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c180 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1c190 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1c1a0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1c1b0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1c1c0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1c1d0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1c1e0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1c1f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c200 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1c210 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1c220 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1c230 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1c240 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c250 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1c260 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1c270 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1c280 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1c290 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1c2a0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1c2b0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1c2c0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1c2d0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1c2e0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1c2f0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1c300 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1c310 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1c320 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1c330 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1c340 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1c350 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1c360 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1c370 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1c380 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1c390 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1c3a0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1c3b0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1c3c0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1c3d0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1c3e0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1c3f0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1c400 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1c410 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c420 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1c430 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1c440 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1c450 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1c460 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1c470 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1c480 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1c490 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1c4a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c4b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1c4c0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1c4d0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1c4e0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1c4f0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1c500 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1c510 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1c520 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1c530 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1c540 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1c550 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69  ing option is li
1c560 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74  ke "%q" except t
1c570 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74  hat it expects t
1c580 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65  o.** be containe
1c590 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d  d within double-
1c5a0 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f  quotes instead o
1c5b0 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c  f single quotes,
1c5c0 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70   and it.** escap
1c5d0 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75  es the double-qu
1c5e0 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e  ote character in
1c5f0 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e  stead of the sin
1c600 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61  gle-quote.** cha
1c610 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22  racter.)^  The "
1c620 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1c630 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ption is intende
1c640 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73  d for safely ins
1c650 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20  erting.** table 
1c660 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  and column names
1c670 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63   into a construc
1c680 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1c690 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  t..**.** ^(The "
1c6a0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1c6b0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1c6c0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1c6d0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1c6e0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1c6f0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1c700 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1c710 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1c720 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1c730 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1c740 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1c750 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
1c760 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1c770 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
1c780 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1c790 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1c7a0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
1c7b0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1c7c0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1c7d0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1c7e0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1c7f0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1c800 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1c810 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1c820 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1c830 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1c840 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1c850 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1c860 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1c870 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1c880 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1c890 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1c8a0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1c8b0 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1c8c0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1c8d0 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1c8e0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1c8f0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1c900 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1c910 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1c920 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1c930 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c940 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1c950 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1c960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1c970 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1c980 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c990 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1c9a0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1c9b0 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1c9c0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1c9d0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1c9e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1c9f0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1ca00 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1ca10 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1ca20 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1ca30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ca40 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1ca50 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1ca60 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1ca70 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1ca80 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1ca90 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1caa0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1cab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1cac0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1cad0 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1cae0 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1caf0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1cb00 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1cb10 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1cb20 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1cb30 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1cb40 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1cb50 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1cb60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1cb70 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1cb80 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1cb90 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1cba0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1cbb0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1cbc0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1cbd0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1cbe0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1cbf0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1cc00 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1cc10 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1cc20 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1cc30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1cc40 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1cc50 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1cc60 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1cc70 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1cc80 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1cc90 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1cca0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1ccb0 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1ccc0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1ccd0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1cce0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1ccf0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1cd00 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1cd10 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1cd20 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1cd30 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1cd40 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1cd50 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1cd60 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1cd70 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1cd80 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1cd90 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1cda0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1cdb0 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1cdc0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1cdd0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1cde0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1cdf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1ce00 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1ce10 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1ce20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1ce30 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1ce40 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1ce50 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1ce60 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1ce70 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1ce80 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1ce90 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1cea0 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1ceb0 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1cec0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1ced0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1cee0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1cef0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1cf00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1cf10 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1cf20 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1cf30 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1cf40 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1cf50 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1cf60 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1cf70 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1cf80 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1cf90 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1cfa0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1cfb0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1cfc0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1cfd0 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1cfe0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1cff0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1d000 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1d010 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d020 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1d030 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1d040 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d050 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1d060 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1d070 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1d080 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1d090 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d0a0 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1d0b0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1d0c0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1d0d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d0e0 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1d0f0 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1d100 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1d110 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1d120 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1d130 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d140 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1d150 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1d160 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1d170 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d180 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1d190 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1d1a0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1d1b0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1d1c0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1d1d0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1d1e0 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1d1f0 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1d200 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1d210 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1d220 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1d230 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1d240 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1d250 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1d260 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1d270 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d280 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1d290 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1d2a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1d2b0 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1d2c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1d2d0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d2e0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1d2f0 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1d300 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1d310 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1d320 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1d330 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1d340 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1d350 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1d360 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1d370 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1d380 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1d390 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1d3a0 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1d3b0 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1d3c0 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1d3d0 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1d3e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d3f0 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1d400 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1d410 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1d420 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1d430 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1d440 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1d450 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1d460 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1d470 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1d480 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1d490 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1d4a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1d4b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1d4c0 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1d4d0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1d4e0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1d4f0 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1d500 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1d510 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1d520 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1d530 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1d540 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1d550 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1d560 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1d570 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1d580 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1d590 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1d5a0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1d5b0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1d5c0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1d5d0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1d5e0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1d5f0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1d600 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1d610 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1d620 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1d630 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1d640 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1d650 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1d660 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1d670 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1d680 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1d690 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1d6a0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1d6b0 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1d6c0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1d6d0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1d6e0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1d6f0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1d700 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1d710 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1d720 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1d730 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1d740 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1d750 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1d760 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1d770 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1d780 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1d790 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1d7a0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1d7b0 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1d7c0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1d7d0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1d7e0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1d7f0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1d800 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1d810 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1d820 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1d830 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1d840 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d850 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1d860 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1d870 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1d880 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1d890 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1d8a0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1d8b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1d8c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1d8d0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1d8e0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1d8f0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1d900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1d910 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1d920 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1d930 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1d940 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1d950 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1d960 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1d970 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1d980 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d990 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1d9a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1d9b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1d9c0 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
1d9d0 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73  uint64);.void *s
1d9e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1d9f0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1da00 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1da10 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1da20 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1da30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1da40 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69  id*);.sqlite3_ui
1da50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
1da60 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
1da70 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1da80 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1da90 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1daa0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1dab0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1dac0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1dad0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1dae0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1daf0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1db00 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1db10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1db20 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1db30 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1db40 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1db50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1db60 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1db70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1db80 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1db90 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1dba0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1dbb0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1dbc0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1dbd0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1dbe0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1dbf0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1dc00 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1dc10 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1dc20 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1dc30 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1dc40 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1dc50 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1dc60 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1dc70 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1dc80 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1dc90 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1dca0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1dcb0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1dcc0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1dcd0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1dce0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1dcf0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1dd00 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1dd10 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1dd20 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1dd30 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1dd40 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1dd50 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1dd60 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1dd70 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1dd80 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1dd90 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1dda0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1ddb0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1ddc0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1ddd0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1dde0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1ddf0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1de00 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1de10 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1de20 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1de30 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1de40 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1de50 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1de60 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1de70 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1de80 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1de90 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1dea0 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1deb0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1dec0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1ded0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1dee0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1def0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1df00 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1df10 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1df20 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1df30 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1df40 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1df50 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1df60 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1df70 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1df80 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1df90 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1dfa0 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1dfb0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1dfc0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1dfd0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1dfe0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1dff0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1e000 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1e010 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1e020 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1e030 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1e040 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1e050 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1e060 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1e070 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1e080 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1e090 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1e0a0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1e0b0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1e0c0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1e0d0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1e0e0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1e0f0 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
1e100 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
1e110 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1e120 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1e130 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1e140 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1e150 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1e160 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1e170 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
1e180 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
1e190 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
1e1a0 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
1e1b0 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
1e1c0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1e1d0 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
1e1e0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1e1f0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
1e200 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1e210 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1e220 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1e230 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e240 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1e250 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
1e260 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
1e270 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
1e280 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1e290 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1e2a0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1e2b0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1e2c0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1e2d0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1e2e0 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
1e2f0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1e300 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1e310 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e320 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1e330 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1e340 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
1e350 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1e360 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1e370 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1e380 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1e390 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1e3a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1e3b0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1e3c0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1e3d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1e3e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e3f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1e400 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1e410 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1e420 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1e430 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e440 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1e450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e460 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1e470 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1e480 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1e490 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1e4a0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1e4b0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1e4c0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1e4d0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1e4e0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1e4f0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1e500 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1e510 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e520 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e530 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1e540 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1e550 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1e560 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e570 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1e580 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1e590 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1e5a0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1e5b0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1e5c0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1e5d0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1e5e0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1e5f0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1e600 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1e610 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1e620 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1e630 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1e640 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1e650 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1e660 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1e670 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e680 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1e690 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1e6a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1e6b0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1e6c0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1e6d0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1e6e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e6f0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1e700 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1e710 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1e720 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1e730 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1e740 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1e750 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1e760 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1e770 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1e780 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1e790 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1e7a0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1e7b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e7c0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1e7d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1e7e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1e7f0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1e800 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1e810 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1e820 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1e830 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1e840 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1e850 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1e860 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1e870 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1e880 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1e890 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1e8a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1e8b0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1e8c0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1e8d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e8e0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1e8f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1e900 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1e910 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1e920 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1e930 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1e940 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1e950 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1e960 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1e970 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1e980 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1e990 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1e9a0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1e9b0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1e9c0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1e9d0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1e9e0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1e9f0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1ea00 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1ea10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1ea20 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1ea30 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1ea40 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1ea50 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1ea60 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1ea70 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1ea80 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1ea90 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1eaa0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1eab0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1eac0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1ead0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1eae0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1eaf0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1eb00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1eb10 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1eb20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1eb30 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1eb40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1eb50 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1eb60 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1eb70 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1eb80 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1eb90 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1eba0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1ebb0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1ebc0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ebd0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1ebe0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1ebf0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1ec00 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1ec10 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1ec20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1ec30 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1ec40 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1ec50 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1ec60 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1ec70 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1ec80 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1ec90 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1eca0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1ecb0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1ecc0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1ecd0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1ece0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1ecf0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1ed00 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1ed10 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1ed20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1ed30 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1ed40 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1ed50 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1ed60 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1ed70 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1ed80 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1ed90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1eda0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1edb0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1edc0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1edd0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1ede0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1edf0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1ee00 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1ee10 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1ee20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1ee30 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1ee40 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1ee50 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1ee60 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1ee70 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1ee80 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1ee90 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1eea0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1eeb0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1eec0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1eed0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1eee0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1eef0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1ef00 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1ef10 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1ef20 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1ef30 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1ef40 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1ef50 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1ef60 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1ef70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1ef80 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1ef90 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1efa0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1efb0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1efc0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1efd0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1efe0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1eff0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1f000 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1f010 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1f020 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1f030 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1f040 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1f050 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1f060 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1f070 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1f080 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1f090 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1f0a0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1f0b0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1f0c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1f0d0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1f0e0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1f0f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1f100 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f110 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1f120 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1f130 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1f140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f150 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1f160 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f170 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1f180 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1f190 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1f1a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f1b0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1f1c0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1f1d0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1f1e0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1f1f0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1f200 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1f210 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1f220 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1f230 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1f240 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1f250 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1f260 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1f270 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1f280 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1f290 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1f2a0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1f2b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1f2c0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1f2d0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1f2e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f2f0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1f300 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1f310 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f320 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1f330 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1f340 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1f350 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1f360 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1f370 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1f380 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1f390 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1f3a0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1f3b0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1f3c0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1f3d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1f3e0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1f3f0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1f400 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1f410 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1f420 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1f430 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1f440 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1f450 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1f460 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1f470 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1f480 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1f490 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1f4a0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1f4b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1f4c0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1f4d0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1f4e0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1f4f0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1f500 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1f510 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1f520 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1f530 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1f540 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1f550 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f560 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1f570 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1f580 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1f590 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1f5a0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1f5b0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1f5c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1f5d0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1f5e0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1f5f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1f600 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1f610 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1f620 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1f630 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1f640 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1f650 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1f660 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1f670 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
1f680 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
1f690 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
1f6a0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1f6b0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1f6c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1f6d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f6e0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1f6f0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1f700 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1f710 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1f720 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1f730 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1f740 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1f750 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1f760 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1f770 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1f780 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1f790 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1f7a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1f7b0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1f7c0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1f7d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1f7e0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1f7f0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1f800 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1f810 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1f820 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1f830 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1f840 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1f850 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1f860 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1f870 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1f880 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1f890 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1f8a0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1f8b0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1f8c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1f8d0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1f8e0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1f8f0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1f900 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1f910 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1f920 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1f930 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1f940 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1f950 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1f960 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1f970 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1f980 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1f990 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1f9a0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1f9b0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1f9c0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1f9d0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1f9e0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1f9f0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1fa00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1fa10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1fa20 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1fa30 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1fa40 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1fa50 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1fa60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1fa70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fa80 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1fa90 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1faa0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1fab0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1fac0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1fad0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1fae0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1faf0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1fb00 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1fb10 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1fb20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1fb30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fb40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fb50 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1fb60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1fb70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1fb80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fb90 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1fba0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1fbb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1fbc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fbd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fbe0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1fbf0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1fc00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1fc10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fc20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1fc30 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1fc40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1fc50 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1fc60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fc70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1fc80 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1fc90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1fca0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1fcb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fcc0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1fcd0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1fce0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1fcf0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1fd00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fd10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1fd20 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1fd30 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1fd40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fd50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fd60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1fd70 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1fd80 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1fd90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1fda0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fdb0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1fdc0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1fdd0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1fde0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fdf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fe00 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1fe10 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1fe20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fe30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fe40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fe50 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1fe60 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1fe70 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1fe80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1fe90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fea0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1feb0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1fec0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1fed0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fef0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1ff00 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1ff10 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ff20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ff30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ff40 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1ff50 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1ff60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ff70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ff80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ff90 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1ffa0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1ffb0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1ffc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ffd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ffe0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1fff0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
20000 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20010 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20020 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20030 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
20040 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
20050 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
20060 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20070 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20080 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
20090 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
200a0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
200b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
200c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
200d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
200e0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
200f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20100 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20110 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
20120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
20130 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
20140 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
20150 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
20160 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
20170 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
20180 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20190 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
201a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
201b0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
201c0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
201d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
201e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
201f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20200 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
20210 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
20220 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
20230 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20240 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20250 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
20260 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
20270 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20280 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
20290 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
202a0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
202b0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
202c0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
202d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
202e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
202f0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
20300 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
20310 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
20320 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20340 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
20350 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
20360 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
20370 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20390 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
203a0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
203b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
203c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
203d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
203e0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
203f0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
20400 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20410 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20430 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
20440 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
20450 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
20460 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
20470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20480 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
20490 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
204a0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
204b0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
204c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
204d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
204e0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
204f0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
20500 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
20510 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
20520 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
20530 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
20540 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
20550 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
20560 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
20570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20580 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
20590 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
205a0 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
205b0 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
205c0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
205d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
205e0 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
205f0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
20600 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
20610 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
20620 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
20630 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
20640 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
20650 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
20660 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
20670 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
20680 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
20690 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
206a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
206b0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
206c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
206d0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
206e0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
206f0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
20700 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
20710 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
20720 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
20730 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
20740 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
20750 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
20760 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
20770 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
20780 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
20790 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
207a0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
207b0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
207c0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
207d0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
207e0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
207f0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
20800 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
20810 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
20820 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
20830 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
20840 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
20850 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
20860 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
20870 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
20880 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
20890 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
208a0 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
208b0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
208c0 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
208d0 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
208e0 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
208f0 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
20900 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
20910 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
20920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
20930 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
20940 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
20950 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
20960 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
20970 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
20980 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
20990 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
209a0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
209b0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
209c0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
209d0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
209e0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
209f0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
20a00 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
20a10 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
20a20 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
20a30 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
20a40 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
20a50 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
20a60 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
20a70 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
20a80 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
20a90 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
20aa0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
20ab0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
20ac0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
20ad0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
20ae0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
20af0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
20b00 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
20b10 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
20b20 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
20b30 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
20b40 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
20b50 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
20b60 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
20b70 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
20b80 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
20b90 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
20ba0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20bb0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
20bc0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
20bd0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
20be0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
20bf0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
20c00 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
20c10 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
20c20 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
20c30 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
20c40 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
20c50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
20c60 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
20c70 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
20c80 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
20c90 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
20ca0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
20cb0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
20cc0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
20cd0 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
20ce0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
20cf0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
20d00 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
20d10 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
20d20 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
20d30 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
20d40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
20d50 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
20d60 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
20d70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
20d80 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
20d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
20da0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
20db0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
20dc0 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
20dd0 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
20de0 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
20df0 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
20e00 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
20e10 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
20e20 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
20e30 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
20e40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20e50 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
20e60 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
20e70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
20e80 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
20e90 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
20ea0 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
20eb0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
20ec0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
20ed0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
20ee0 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
20ef0 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
20f00 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
20f10 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
20f20 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
20f30 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
20f40 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
20f50 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
20f60 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
20f70 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
20f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
20f90 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
20fa0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
20fb0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
20fc0 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
20fd0 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
20fe0 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
20ff0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21000 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
21010 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
21020 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
21030 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
21040 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
21050 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
21060 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
21070 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
21080 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
21090 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
210a0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
210b0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
210c0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
210d0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
210e0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
210f0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
21100 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
21110 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
21120 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
21130 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
21140 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
21150 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21160 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
21170 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
21180 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
21190 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
211a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
211b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
211c0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
211d0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
211e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
211f0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21200 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21210 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21220 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
21230 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
21240 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
21250 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
21260 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
21270 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
21280 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
21290 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e  onnection.** CON
212a0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
212b0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  3.**.** ^These r
212c0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
212d0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
212e0 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
212f0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
21300 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
21310 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
21320 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
21330 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
21340 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
21350 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
21360 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
21370 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
21380 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
21390 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
213a0 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
213b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
213c0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
213d0 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
213e0 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
213f0 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
21400 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
21410 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
21420 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
21430 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
21440 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
21450 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
21460 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
21470 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
21480 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
21490 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
214a0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
214b0 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
214c0 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
214d0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
214e0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
214f0 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
21500 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
21510 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
21520 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
21530 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
21540 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
21550 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
21560 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
21570 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
21580 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
21590 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
215a0 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
215b0 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
215c0 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
215d0 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
215e0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
215f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
21600 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
21610 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
21620 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
21630 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
21640 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
21650 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21660 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
21670 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
21680 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
21690 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
216a0 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
216b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
216c0 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
216d0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
216e0 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
216f0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
21700 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
21710 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
21720 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
21730 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
21740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21750 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
21760 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
21770 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
21780 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
21790 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
217a0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
217b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
217c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
217d0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
217e0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
217f0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
21800 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
21810 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
21820 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
21830 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
21840 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
21850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21860 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
21870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
21880 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21890 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
218a0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
218b0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
218c0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
218d0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
218e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
218f0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
21900 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
21910 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
21920 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
21930 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
21940 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
21950 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
21960 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
21970 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
21980 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
21990 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
219a0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
219b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
219c0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
219d0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
219e0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
219f0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
21a00 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21a10 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
21a20 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
21a30 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
21a40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
21a50 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21a60 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
21a70 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
21a80 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
21a90 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
21aa0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
21ab0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
21ac0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
21ad0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
21ae0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
21af0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
21b00 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
21b10 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
21b20 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
21b30 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21b40 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
21b50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
21b60 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
21b70 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
21b80 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21b90 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
21ba0 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
21bb0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
21bc0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
21bd0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
21be0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
21bf0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
21c00 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
21c10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
21c20 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
21c30 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
21c40 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
21c50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
21c60 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
21c70 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
21c80 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
21c90 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
21ca0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
21cb0 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
21cc0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
21cd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
21ce0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
21cf0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
21d00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
21d10 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
21d20 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
21d30 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
21d40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21d50 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
21d60 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
21d70 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
21d80 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
21d90 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
21da0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
21db0 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
21dc0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
21dd0 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
21de0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21df0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
21e00 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
21e10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21e20 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
21e30 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
21e40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
21e50 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
21e60 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
21e70 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
21e80 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
21e90 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
21ea0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
21eb0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
21ec0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
21ed0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21ee0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
21ef0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
21f00 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
21f10 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
21f20 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21f30 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
21f40 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
21f50 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
21f60 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
21f70 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
21f80 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
21f90 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
21fa0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
21fb0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
21fc0 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
21fd0 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
21fe0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
21ff0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
22000 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
22010 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
22020 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
22030 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22040 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
22050 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
22060 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
22070 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
22080 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
22090 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
220a0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
220b0 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
220c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
220d0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
220e0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
220f0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
22100 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
22110 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
22120 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
22130 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
22140 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
22150 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
22160 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
22170 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
22180 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
22190 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
221a0 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
221b0 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
221c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
221d0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
221e0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
221f0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
22200 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
22210 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
22220 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
22230 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
22240 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
22250 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
22260 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
22270 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
22280 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
22290 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
222a0 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
222b0 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
222c0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
222d0 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
222e0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
222f0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
22300 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
22310 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
22320 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
22330 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
22340 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
22350 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
22360 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
22370 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
22380 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
22390 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
223a0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
223b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
223c0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
223d0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
223e0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
223f0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
22400 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
22410 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
22420 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
22430 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
22440 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
22450 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
22460 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
22470 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
22480 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
22490 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
224a0 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
224b0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
224c0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
224d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
224e0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
224f0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
22500 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
22510 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
22520 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
22530 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
22540 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
22550 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
22560 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
22570 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
22580 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
22590 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
225a0 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
225b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
225c0 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
225d0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
225e0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
225f0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
22600 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
22610 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
22620 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
22630 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
22640 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
22650 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
22660 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
22670 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
22680 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
22690 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
226a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
226b0 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
226c0 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
226d0 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
226e0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
226f0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
22700 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
22710 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
22720 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
22730 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
22740 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
22750 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
22760 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
22770 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
22780 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
22790 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
227a0 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
227b0 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
227c0 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
227d0 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
227e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
227f0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
22800 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
22810 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
22820 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
22830 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
22840 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
22850 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
22860 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
22870 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
22880 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
22890 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
228a0 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
228b0 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
228c0 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
228d0 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
228e0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
228f0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
22900 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
22910 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
22920 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
22930 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
22940 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
22950 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
22960 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
22970 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
22980 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
22990 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
229a0 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
229b0 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
229c0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
229d0 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
229e0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
229f0 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
22a00 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
22a10 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
22a20 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
22a30 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
22a40 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
22a50 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
22a60 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
22a70 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
22a80 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
22a90 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
22aa0 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
22ab0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
22ac0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
22ad0 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
22ae0 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
22af0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
22b00 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
22b10 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
22b20 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
22b30 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
22b40 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
22b50 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
22b60 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
22b70 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
22b80 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
22b90 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
22ba0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
22bb0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22bc0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
22bd0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
22be0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
22bf0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
22c00 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
22c10 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
22c20 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
22c30 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
22c40 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
22c50 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
22c60 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
22c70 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
22c80 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
22c90 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
22ca0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
22cb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
22cc0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22cd0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
22ce0 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
22cf0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
22d00 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
22d10 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
22d20 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
22d30 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
22d40 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
22d50 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
22d60 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
22d70 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
22d80 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
22d90 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
22da0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
22db0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
22dc0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
22dd0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
22de0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
22df0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
22e00 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
22e10 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
22e20 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
22e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22e40 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
22e50 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
22e60 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
22e70 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
22e80 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22e90 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
22ea0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
22eb0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
22ec0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
22ed0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
22ee0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
22ef0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
22f00 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
22f10 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
22f20 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
22f30 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
22f40 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
22f50 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
22f60 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
22f70 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
22f80 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
22f90 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
22fa0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
22fb0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
22fc0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
22fd0 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
22fe0 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
22ff0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
23000 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
23010 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
23020 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
23030 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
23040 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
23050 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
23060 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
23070 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
23080 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23090 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
230a0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
230b0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
230c0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
230d0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
230e0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
230f0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
23100 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
23110 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
23120 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
23130 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
23140 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
23150 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
23160 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
23170 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
23180 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
23190 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
231a0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
231b0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
231c0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" 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 20 53 51 4c 49 54 45  tting the SQLITE
231f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
23200 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
23210 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
23220 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
23230 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
23240 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
23250 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
23260 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
23270 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
23280 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
23290 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
232a0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
232b0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
232c0 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
232d0 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
232e0 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
232f0 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
23300 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
23310 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
23320 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
23330 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
23340 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
23350 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
23360 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
23370 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
23380 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
23390 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
233a0 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
233b0 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
233c0 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
233d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
233e0 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
233f0 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
23400 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
23410 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
23420 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
23430 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
23440 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
23450 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
23460 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
23470 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
23480 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
23490 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
234a0 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
234b0 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
234c0 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
234d0 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
234e0 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
234f0 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
23500 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
23510 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
23520 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
23530 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
23540 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
23550 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
23560 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
23570 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
23580 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
23590 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
235a0 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
235b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
235c0 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
235d0 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
235e0 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
235f0 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
23600 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
23610 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
23620 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
23630 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
23640 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
23650 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
23660 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
23670 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
23680 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
23690 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
236a0 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
236b0 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
236c0 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
236d0 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
236e0 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
236f0 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
23700 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
23710 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
23720 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
23730 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
23740 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
23750 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
23760 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
23770 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
23780 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
23790 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
237a0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
237b0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
237c0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
237d0 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
237e0 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
237f0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
23800 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
23810 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
23820 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
23830 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
23840 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
23850 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
23860 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
23870 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
23880 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
23890 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
238a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
238b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
238c0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
238d0 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
238e0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
238f0 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
23900 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
23910 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
23920 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
23930 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
23940 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
23950 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23960 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
23970 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
23980 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
23990 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
239a0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
239b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
239c0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
239d0 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
239e0 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
239f0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
23a00 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
23a10 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
23a20 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
23a30 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
23a40 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
23a50 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
23a60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23a70 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
23a80 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
23a90 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23aa0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23ab0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
23ac0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
23ad0 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
23ae0 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
23af0 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
23b00 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
23b10 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23b20 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
23b30 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
23b40 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
23b50 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
23b60 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
23b70 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
23b80 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
23b90 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
23ba0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
23bb0 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
23bc0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
23bd0 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
23be0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
23bf0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
23c00 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
23c10 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
23c20 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
23c30 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
23c40 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
23c50 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
23c60 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
23c70 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
23c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
23c90 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
23ca0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
23cb0 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
23cc0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
23cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
23ce0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
23cf0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
23d00 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
23d10 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
23d20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
23d30 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
23d40 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
23d50 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
23d60 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
23d70 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
23d80 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
23d90 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
23da0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
23db0 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
23dc0 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
23dd0 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
23de0 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
23df0 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
23e00 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
23e10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23e20 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
23e30 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
23e40 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
23e50 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
23e60 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
23e70 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
23e80 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
23e90 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
23ea0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
23eb0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
23ec0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
23ed0 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
23ee0 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
23ef0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23f00 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
23f10 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
23f20 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
23f30 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
23f40 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
23f50 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
23f60 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
23f70 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
23f80 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
23f90 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
23fa0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
23fb0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
23fc0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
23fd0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
23fe0 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
23ff0 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
24000 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
24010 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
24020 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
24030 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
24040 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
24050 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
24060 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
24070 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
24080 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
24090 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
240a0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
240b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
240c0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
240d0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
240e0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
240f0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
24100 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
24110 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
24120 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
24130 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
24140 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
24150 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
24160 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
24170 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
24180 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
24190 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
241a0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
241b0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
241c0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
241d0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
241e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
241f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
24200 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
24210 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
24220 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
24230 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
24240 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
24250 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
24260 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
24270 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
24280 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
24290 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
242a0 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
242b0 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
242c0 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
242d0 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
242e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
242f0 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
24300 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74  irectory].*/.int
24310 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
24320 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
24330 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
24340 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
24350 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
24360 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
24370 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
24380 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
24390 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
243a0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
243b0 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
243c0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
243d0 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
243e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
243f0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
24400 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
24410 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
24420 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
24430 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
24440 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
24450 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
24460 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
24470 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
24480 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
24490 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
244a0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
244b0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
244c0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
244d0 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
244e0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
244f0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
24500 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24510 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
24520 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
24530 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
24540 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
24550 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
24560 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
24570 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
24580 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
24590 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
245a0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
245b0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
245c0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
245d0 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
245e0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
245f0 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
24600 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
24610 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
24620 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
24630 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
24640 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
24650 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
24660 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
24670 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
24680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
24690 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
246a0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
246b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
246c0 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
246d0 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
246e0 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
246f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24700 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24710 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
24720 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24730 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
24740 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
24750 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
24760 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
24770 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
24780 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
24790 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
247a0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
247b0 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
247c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
247d0 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
247e0 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
247f0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
24800 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
24810 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
24820 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
24830 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
24840 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24850 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
24860 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
24870 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
24880 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
24890 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
248a0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
248b0 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
248c0 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
248d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
248e0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
248f0 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
24900 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
24910 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
24920 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
24930 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
24940 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
24950 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
24960 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
24970 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
24980 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
24990 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
249a0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
249b0 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
249c0 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
249d0 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
249e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
249f0 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
24a00 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
24a10 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
24a20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
24a30 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
24a40 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
24a50 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
24a60 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
24a70 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24a80 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
24a90 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
24aa0 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
24ab0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24ac0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
24ad0 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
24ae0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
24af0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
24b00 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
24b10 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24b20 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
24b30 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
24b40 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
24b50 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
24b60 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
24b70 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
24b80 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
24b90 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
24ba0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
24bb0 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
24bc0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
24bd0 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
24be0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
24bf0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
24c00 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
24c10 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
24c20 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
24c30 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
24c40 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
24c50 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
24c60 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
24c70 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
24c80 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
24c90 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
24ca0 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
24cb0 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
24cc0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
24cd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
24ce0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
24cf0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
24d00 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
24d10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
24d20 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
24d30 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
24d40 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
24d50 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
24d60 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24d70 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
24d80 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
24d90 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
24da0 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
24db0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
24dc0 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
24dd0 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
24de0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
24df0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
24e00 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
24e10 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d  nd Messages.** M
24e20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
24e30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
24e40 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
24e50 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
24e60 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
24e70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24e80 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
24e90 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
24ea0 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
24eb0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
24ec0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
24ed0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
24ee0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24ef0 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
24f00 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
24f10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24f20 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
24f30 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
24f40 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
24f50 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
24f60 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
24f70 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
24f80 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24f90 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
24fa0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24fb0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24fc0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24fd0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
24fe0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24ff0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
25000 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
25010 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
25020 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
25030 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
25040 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
25050 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
25060 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
25070 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
25080 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
25090 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
250a0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
250b0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
250c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
250d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
250e0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
250f0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
25100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
25110 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
25120 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
25130 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
25140 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
25150 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
25160 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
25170 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
25180 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
25190 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
251a0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
251b0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
251c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
251d0 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
251e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
251f0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
25200 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
25210 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
25220 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
25230 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
25240 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
25250 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
25260 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
25270 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
25280 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
25290 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
252a0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
252b0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
252c0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
252d0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
252e0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
252f0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
25300 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
25310 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
25320 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
25330 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
25340 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
25350 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
25360 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
25370 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
25380 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
25390 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
253a0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
253b0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
253c0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
253d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
253e0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
253f0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
25400 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
25410 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
25420 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
25430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
25440 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
25450 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
25460 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
25470 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
25480 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
25490 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
254a0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
254b0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
254c0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
254d0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
254e0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
254f0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
25500 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
25510 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
25520 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
25530 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
25540 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
25550 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
25560 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
25570 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
25580 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
25590 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
255a0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
255b0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
255c0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
255d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
255e0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
255f0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
25600 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
25610 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
25620 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25630 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
25640 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
25650 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
25660 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
25670 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25680 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
25690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
256a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
256b0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
256c0 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
256d0 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
256e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
256f0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
25700 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
25710 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
25720 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
25730 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
25740 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
25750 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
25760 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
25770 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
25780 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
25790 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
257a0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
257b0 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
257c0 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
257d0 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
257e0 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
257f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
25800 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
25810 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
25820 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
25830 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
25840 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
25850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
25860 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
25870 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
25880 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
25890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
258a0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
258b0 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
258c0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
258d0 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
258e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
258f0 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
25900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25910 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
25920 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
25930 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
25940 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
25950 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
25960 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
25970 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
25980 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
25990 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
259a0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
259b0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
259c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
259d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
259e0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
259f0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
25a00 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
25a10 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
25a20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
25a30 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
25a40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
25a50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
25a60 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
25a70 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
25a80 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
25a90 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
25aa0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
25ab0 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
25ac0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
25ad0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
25ae0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
25af0 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
25b00 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
25b10 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
25b20 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
25b30 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
25b40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
25b50 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
25b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25b70 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
25b80 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
25b90 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
25ba0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25bb0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
25bc0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
25bd0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
25be0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
25bf0 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
25c00 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
25c10 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
25c20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
25c30 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
25c40 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
25c50 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
25c60 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
25c70 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
25c80 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
25c90 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
25ca0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
25cb0 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
25cc0 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
25cd0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
25ce0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
25cf0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
25d00 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
25d10 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
25d20 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
25d30 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
25d40 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
25d50 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
25d60 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
25d70 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
25d80 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
25d90 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
25da0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
25db0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
25dc0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
25dd0 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
25de0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25df0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
25e00 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25e10 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
25e20 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
25e30 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
25e40 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
25e50 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
25e60 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
25e70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
25e80 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
25e90 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
25ea0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
25eb0 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
25ec0 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
25ed0 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
25ee0 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
25ef0 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
25f00 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
25f10 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
25f20 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
25f30 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
25f40 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
25f50 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
25f60 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
25f70 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
25f80 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
25f90 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
25fa0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
25fb0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
25fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
25fd0 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
25fe0 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
25ff0 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
26000 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
26010 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
26020 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
26030 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
26040 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
26050 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
26060 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
26070 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
26080 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
26090 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
260a0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
260b0 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
260c0 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
260d0 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
260e0 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
260f0 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
26100 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
26110 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
26120 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
26130 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
26140 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
26150 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
26160 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
26170 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
26180 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
26190 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
261a0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
261b0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
261c0 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
261d0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
261e0 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
261f0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
26200 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
26210 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
26220 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
26230 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
26240 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
26250 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
26260 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
26270 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
26280 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
26290 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
262a0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
262b0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
262c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
262d0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
262e0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
262f0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
26300 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
26310 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
26320 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
26330 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
26340 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
26350 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
26360 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
26370 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
26380 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
26390 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
263a0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
263b0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
263c0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
263d0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
263e0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
263f0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
26400 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26410 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
26420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
26430 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
26440 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
26450 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
26460 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
26470 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
26480 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26490 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
264a0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
264b0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
264c0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
264d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
264e0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
264f0 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
26500 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
26510 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
26520 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
26530 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
26540 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
26550 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26560 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
26570 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
26580 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
26590 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
265a0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
265b0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
265c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
265d0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
265e0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
265f0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
26600 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26610 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
26620 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
26630 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
26640 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
26650 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
26660 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
26670 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
26680 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
26690 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
266a0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
266b0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
266c0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
266d0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
266e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
266f0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
26700 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
26710 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
26720 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26730 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
26740 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
26750 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
26760 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
26770 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26780 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
26790 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
267a0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
267b0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
267c0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
267d0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
267e0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
267f0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
26800 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
26810 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
26820 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
26830 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
26840 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26850 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
26860 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
26870 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26880 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
26890 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
268a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
268b0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
268c0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
268d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
268e0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
268f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
26900 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
26910 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26920 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
26930 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
26940 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
26950 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26960 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
26970 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
26980 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26990 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
269a0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
269b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
269c0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
269d0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
269e0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
269f0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
26a00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26a10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
26a20 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
26a30 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
26a40 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
26a50 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
26a60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
26a70 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
26a80 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
26a90 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
26aa0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
26ab0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
26ac0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
26ad0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26ae0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
26af0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26b00 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
26b10 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
26b20 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
26b30 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26b40 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
26b50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26b60 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
26b70 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
26b80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26b90 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
26ba0 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
26bb0 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
26bc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26bd0 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
26be0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
26bf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
26c00 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
26c10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26c20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
26c30 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
26c40 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
26c50 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
26c60 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
26c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26c80 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
26c90 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
26ca0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
26cb0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
26cc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26cd0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
26ce0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
26cf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
26d00 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
26d10 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
26d20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26d30 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
26d40 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
26d50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
26d60 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
26d70 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
26d80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
26d90 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
26da0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
26db0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26dc0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
26dd0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
26de0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26df0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
26e00 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
26e10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26e20 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
26e30 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
26e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
26e50 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
26e60 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
26e70 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
26e80 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
26e90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
26ea0 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
26eb0 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
26ec0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
26ed0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
26ee0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
26ef0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
26f00 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
26f10 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
26f20 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
26f30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
26f40 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
26f50 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
26f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
26f70 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
26f80 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
26f90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26fa0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
26fb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
26fc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
26fd0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
26fe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26ff0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
27000 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
27010 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
27020 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
27030 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
27040 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
27050 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
27060 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
27070 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
27080 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
27090 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
270a0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
270b0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
270c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
270d0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
270e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
270f0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
27100 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27110 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
27120 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
27130 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
27140 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
27150 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
27160 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
27170 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
27180 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
27190 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
271a0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
271b0 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
271c0 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
271d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
271e0 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
271f0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
27200 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
27210 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
27220 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
27230 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
27240 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
27250 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
27260 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
27270 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
27280 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
27290 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
272a0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
272b0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
272c0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
272d0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
272e0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
272f0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
27300 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
27310 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
27320 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
27330 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
27340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27350 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
27360 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
27370 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
27380 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
27390 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
273a0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
273b0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
273c0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
273d0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
273e0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
273f0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
27400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27410 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
27420 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
27430 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27440 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
27450 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
27460 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
27470 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
27480 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
27490 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
274a0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
274b0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
274c0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
274d0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
274e0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
274f0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
27500 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
27510 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
27520 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
27530 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
27540 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27550 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
27560 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
27570 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
27580 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
27590 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
275a0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
275b0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
275c0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
275d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
275e0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
275f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
27600 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
27610 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
27620 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
27630 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27640 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
27650 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
27660 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
27670 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
27680 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
27690 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
276a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
276b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
276c0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
276d0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
276e0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
276f0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
27700 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
27710 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
27720 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
27730 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
27740 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
27750 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
27760 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
27770 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
27780 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
27790 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
277a0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
277b0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
277c0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
277d0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
277e0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
277f0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
27800 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
27810 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
27820 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
27830 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
27840 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
27850 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
27860 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
27870 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
27880 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
27890 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
278a0 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
278b0 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
278c0 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
278d0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
278e0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
278f0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
27900 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
27910 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
27920 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
27930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27940 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
27950 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
27960 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
27970 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
27980 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
27990 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
279a0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
279b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
279c0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
279d0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
279e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
279f0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
27a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
27a10 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
27a20 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
27a30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
27a40 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
27a50 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
27a60 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
27a70 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
27a80 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
27a90 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
27aa0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
27ab0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
27ac0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
27ad0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
27ae0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
27af0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
27b00 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
27b10 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
27b20 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
27b30 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
27b40 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
27b50 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
27b60 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
27b70 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
27b80 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
27b90 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
27ba0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
27bb0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
27bc0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
27bd0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
27be0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
27bf0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
27c00 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
27c10 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
27c20 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
27c30 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
27c40 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
27c50 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
27c60 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
27c70 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
27c80 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
27c90 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
27ca0 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
27cb0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
27cc0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
27cd0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
27ce0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
27cf0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
27d00 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
27d10 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
27d20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
27d30 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
27d40 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
27d50 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
27d60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
27d70 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
27d80 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
27d90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27da0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
27db0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
27dc0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
27dd0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27de0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
27df0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
27e00 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
27e10 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27e20 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27e30 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27e40 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27e50 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27e60 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27e70 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27e80 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27e90 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
27ea0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27eb0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27ec0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
27ed0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
27ee0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
27ef0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27f00 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27f10 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27f20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27f30 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27f40 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
27f50 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27f60 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27f70 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27f80 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27f90 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27fa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27fb0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27fc0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27fd0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27fe0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27ff0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28000 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28010 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
28020 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28030 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
28040 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28050 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28060 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28070 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28080 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
28090 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
280a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
280b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
280c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
280d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
280e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
280f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28100 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28110 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28120 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
28130 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
28140 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
28150 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
28160 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
28170 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
28180 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
28190 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
281a0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
281b0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
281c0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
281d0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
281e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
281f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
28200 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
28210 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
28220 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
28230 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
28240 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
28250 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
28260 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
28270 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
28280 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
28290 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
282a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
282b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
282c0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
282d0 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t SQL.** METHOD:
282e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
282f0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
28300 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
28310 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
28320 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
28330 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
28340 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
28350 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
28360 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
28370 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
28380 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
28390 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
283a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
283b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
283c0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
283d0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
283e0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
283f0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28410 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
28420 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
28430 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
28440 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
28450 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
28460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
28470 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
28480 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28490 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
284a0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
284b0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
284c0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
284d0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
284e0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
284f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
28500 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
28510 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
28520 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28530 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
28540 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
28550 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
28560 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28570 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
28580 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
28590 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
285a0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
285b0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
285c0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
285d0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
285e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
285f0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
28600 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
28610 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
28620 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28630 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
28640 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
28650 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
28660 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
28670 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
28680 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
28690 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
286a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
286b0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
286c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
286d0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
286e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
286f0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
28700 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28710 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
28720 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
28730 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
28740 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
28750 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
28760 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
28770 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
28780 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
28790 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
287a0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
287b0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
287c0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
287d0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
287e0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
287f0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
28800 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
28810 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
28820 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
28830 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
28840 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
28850 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
28860 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
28870 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
28880 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
28890 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
288a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
288b0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
288c0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
288d0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
288e0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
288f0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
28900 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
28910 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
28920 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
28930 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
28940 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
28950 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
28960 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
28970 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
28980 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
28990 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
289a0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
289b0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
289c0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
289d0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
289e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
289f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
28a00 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
28a10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
28a20 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
28a30 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
28a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28a50 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
28a60 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
28a70 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
28a80 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
28a90 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
28aa0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
28ab0 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
28ac0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
28ad0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
28ae0 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
28af0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
28b00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
28b10 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
28b20 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
28b30 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
28b40 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
28b50 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
28b60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
28b70 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
28b80 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
28b90 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
28ba0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
28bb0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
28bc0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
28bd0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
28be0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
28bf0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
28c00 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
28c10 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
28c20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
28c30 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
28c40 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
28c50 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
28c60 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
28c70 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
28c80 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
28c90 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
28ca0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
28cb0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
28cc0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
28cd0 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
28ce0 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
28cf0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
28d00 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
28d10 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
28d20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
28d30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28d40 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
28d50 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
28d60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
28d70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28d80 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
28d90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28da0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
28db0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
28dc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
28dd0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
28de0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
28df0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
28e00 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
28e10 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
28e20 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
28e30 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
28e40 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
28e50 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
28e60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28e70 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
28e80 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
28e90 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
28ea0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
28eb0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
28ec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28ed0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
28ee0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
28ef0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
28f00 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
28f10 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
28f20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28f30 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
28f40 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
28f50 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
28f60 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
28f70 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
28f80 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
28f90 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
28fa0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
28fb0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
28fc0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
28fd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
28fe0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
28ff0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29000 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
29010 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
29020 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
29030 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
29040 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
29050 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
29060 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
29070 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
29080 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
29090 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
290a0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
290b0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
290c0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
290d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
290e0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
290f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
29100 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
29110 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
29120 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
29130 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
29140 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
29150 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
29160 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
29170 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
29180 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
29190 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
291a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
291b0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
291c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
291d0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
291e0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
291f0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
29200 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
29210 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29220 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
29230 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
29240 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
29250 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
29260 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
29270 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
29280 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
29290 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
292a0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
292b0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
292c0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
292d0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
292e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
292f0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
29300 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
29310 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
29320 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
29330 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
29340 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
29350 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
29360 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
29370 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
29380 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
29390 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
293a0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
293b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
293c0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
293d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
293e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
293f0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
29400 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
29410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29420 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
29430 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
29440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
29450 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
29460 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
29470 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
29480 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
29490 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
294a0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
294b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
294c0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
294d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
294e0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
294f0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
29500 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
29510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
29520 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
29530 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
29540 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
29550 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
29560 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
29570 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
29580 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
29590 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
295a0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
295b0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
295c0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
295d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
295e0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
295f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
29600 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
29610 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29620 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
29630 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
29640 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
29650 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
29660 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
29670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29680 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
29690 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
296a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
296b0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
296c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
296d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
296e0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
296f0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
29700 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
29710 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
29720 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
29730 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
29740 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
29750 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
29760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29770 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
29780 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
29790 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
297a0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
297b0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
297c0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
297d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
297e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
297f0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
29800 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
29810 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
29820 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29830 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
29840 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
29850 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
29860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
29870 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
29880 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
29890 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
298a0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
298b0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
298c0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
298d0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
298e0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
298f0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
29900 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
29910 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
29920 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
29930 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
29940 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
29950 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
29960 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
29970 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
29980 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
29990 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
299a0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
299b0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
299c0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
299d0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
299e0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
299f0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
29a00 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
29a10 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
29a20 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
29a30 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
29a40 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
29a50 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
29a60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
29a70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29a80 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
29a90 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
29aa0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
29ab0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
29ac0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
29ad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29ae0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
29af0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
29b00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
29b10 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
29b20 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
29b30 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
29b40 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
29b50 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
29b60 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
29b70 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
29b80 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
29b90 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
29ba0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
29bb0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
29bc0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
29bd0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
29be0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
29bf0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
29c00 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
29c10 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
29c20 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
29c30 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
29c40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29c50 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29c60 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
29c70 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
29c80 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
29c90 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
29ca0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
29cb0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
29cc0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
29cd0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
29ce0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
29cf0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
29d00 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29d10 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
29d20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
29d30 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
29d40 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
29d50 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
29d60 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
29d70 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
29d80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29d90 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
29da0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29db0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
29dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29dd0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
29de0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
29df0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
29e00 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
29e10 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
29e20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
29e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
29e40 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
29e50 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
29e60 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
29e70 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
29e80 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
29e90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29ea0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
29eb0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
29ec0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
29ed0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
29ee0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
29ef0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
29f00 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
29f10 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
29f20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29f30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
29f40 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
29f50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29f60 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
29f70 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
29f80 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
29f90 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
29fa0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
29fb0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
29fc0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
29fd0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
29fe0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
29ff0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2a000 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2a010 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2a020 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2a030 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2a040 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2a050 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2a060 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a070 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2a080 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2a090 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2a0a0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2a0b0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2a0c0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2a0d0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2a0e0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2a0f0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2a100 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2a110 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2a120 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2a130 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2a140 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2a150 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2a160 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2a170 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2a180 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2a190 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2a1a0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2a1b0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2a1c0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2a1d0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2a1e0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2a1f0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2a200 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2a210 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2a220 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2a230 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2a240 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2a250 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2a260 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2a270 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2a280 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2a290 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2a2a0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2a2b0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2a2c0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2a2d0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2a2e0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2a2f0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2a300 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2a310 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2a320 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2a330 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2a340 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2a350 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2a360 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2a370 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2a380 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2a390 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2a3a0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2a3b0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2a3c0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
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 68 61 73 20 74 68 65  argument has the
2a3f0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2a400 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2a410 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2a420 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2a430 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2a440 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2a450 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2a460 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2a470 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2a480 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2a490 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2a4a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2a4b0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2a4c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2a4d0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2a4e0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2a4f0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2a500 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2a510 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2a520 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2a530 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2a540 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2a550 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2a560 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a570 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2a580 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2a590 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2a5a0 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2a5b0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2a5c0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2a5d0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2a5e0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2a5f0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2a600 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2a610 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2a620 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2a630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2a640 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2a650 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2a660 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2a670 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2a680 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2a690 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2a6a0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2a6b0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2a6c0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2a6d0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2a6e0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2a6f0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2a700 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2a710 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2a720 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2a730 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2a740 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2a750 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2a760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2a770 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2a780 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2a790 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2a7a0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2a7b0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2a7c0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2a7d0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2a7e0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2a7f0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a800 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2a810 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2a820 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2a830 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2a840 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2a850 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2a860 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2a870 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2a880 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2a890 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2a8a0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2a8b0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2a8c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2a8d0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2a8e0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2a8f0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2a900 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2a910 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2a920 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2a930 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2a940 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2a950 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2a960 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2a970 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2a980 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2a990 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2a9a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a9b0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2a9c0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2a9d0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2a9e0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2a9f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2aa00 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2aa10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2aa20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2aa30 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2aa40 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2aa50 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2aa60 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2aa70 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2aa80 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2aa90 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2aaa0 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2aab0 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2aac0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2aad0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2aae0 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2aaf0 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2ab00 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2ab10 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2ab20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2ab30 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2ab40 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2ab50 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2ab60 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2ab70 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2ab80 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2ab90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2aba0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2abb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2abc0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2abd0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2abe0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2abf0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2ac00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2ac10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ac20 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2ac30 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2ac40 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2ac50 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2ac60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ac70 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2ac80 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2ac90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aca0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2acb0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2acc0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
2acd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ace0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
2acf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2ad00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2ad10 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
2ad20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2ad30 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2ad40 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2ad50 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
2ad60 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2ad70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2ad80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2ad90 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
2ada0 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
2adb0 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
2adc0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2add0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ade0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2adf0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2ae00 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2ae10 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2ae20 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2ae30 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2ae40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
2ae50 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2ae60 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2ae70 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2ae80 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
2ae90 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
2aea0 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
2aeb0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2aec0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2aed0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2aee0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2aef0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2af00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2af10 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2af20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2af30 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2af40 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2af50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2af60 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2af70 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2af80 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2af90 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2afa0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2afb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2afc0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2afd0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2afe0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2aff0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2b000 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2b010 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2b020 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2b030 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2b040 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2b050 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2b060 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2b070 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2b080 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2b090 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2b0a0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2b0b0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2b0c0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2b0d0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2b0e0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2b0f0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2b100 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2b110 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2b120 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2b130 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2b140 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2b150 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2b160 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2b170 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2b180 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2b190 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b1a0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2b1b0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2b1c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b1d0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2b1e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2b1f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2b200 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2b210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b220 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2b230 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b240 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2b250 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2b260 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
2b270 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b280 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b290 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b2a0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2b2b0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2b2c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2b2d0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2b2e0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2b2f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b300 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2b310 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2b320 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2b330 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2b340 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2b350 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2b360 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2b370 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2b380 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2b390 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2b3a0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2b3b0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2b3c0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2b3d0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2b3e0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2b3f0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2b400 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2b410 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2b420 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2b430 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2b440 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2b450 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2b460 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2b470 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2b480 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2b490 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2b4a0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2b4b0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2b4c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2b4d0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2b4e0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2b4f0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2b500 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2b510 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2b520 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2b530 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2b540 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2b550 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2b560 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2b570 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2b580 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2b590 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2b5a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b5b0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2b5c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b5d0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2b5e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b5f0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2b600 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2b610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b620 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2b630 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2b640 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2b650 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2b660 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b670 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2b680 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2b690 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2b6a0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2b6b0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2b6c0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2b6d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2b6e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2b6f0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2b700 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2b710 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2b720 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2b730 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2b740 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2b750 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2b760 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2b770 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2b780 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2b790 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2b7a0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2b7b0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2b7c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2b7d0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2b7e0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2b7f0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2b800 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2b810 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2b820 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2b830 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2b840 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2b850 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b860 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2b870 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2b880 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2b890 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2b8a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b8b0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2b8c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b8d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b8e0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2b8f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b900 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
2b910 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
2b920 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
2b930 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2b940 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
2b950 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
2b960 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
2b970 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2b980 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2b990 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2b9a0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2b9b0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2b9c0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2b9d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2b9e0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2b9f0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2ba00 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2ba10 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2ba20 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2ba30 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2ba40 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
2ba50 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2ba60 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2ba70 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2ba80 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2ba90 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2baa0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
2bab0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2bac0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2bad0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2bae0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2baf0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
2bb00 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
2bb10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
2bb20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2bb30 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
2bb40 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
2bb50 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
2bb60 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
2bb70 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2bb80 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
2bb90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2bba0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2bbb0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2bbc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
2bbd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2bbe0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2bbf0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
2bc00 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
2bc10 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2bc20 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2bc30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2bc40 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2bc50 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2bc60 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2bc70 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2bc80 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2bc90 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2bca0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2bcb0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2bcc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2bcd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2bce0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2bcf0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2bd00 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2bd10 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2bd20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2bd30 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2bd40 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2bd50 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2bd60 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2bd70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bd80 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2bd90 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2bda0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2bdb0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2bdc0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2bdd0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2bde0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2bdf0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2be00 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2be10 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2be20 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2be30 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2be40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2be50 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2be60 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2be70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2be80 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2be90 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2bea0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2beb0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2bec0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2bed0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2bee0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2bef0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2bf00 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2bf10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2bf20 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2bf30 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2bf40 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2bf50 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2bf60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2bf70 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2bf80 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2bf90 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2bfa0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2bfb0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2bfc0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2bfd0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2bfe0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2bff0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2c000 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2c010 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2c020 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2c030 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2c040 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2c050 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2c060 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2c070 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2c080 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2c090 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2c0a0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2c0b0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2c0c0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2c0d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2c0e0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2c0f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2c100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2c110 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c120 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2c130 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c140 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2c150 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2c160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c170 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2c180 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2c190 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2c1a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c1b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2c1c0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
2c1d0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
2c1e0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2c1f0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
2c200 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
2c210 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
2c220 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
2c230 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
2c240 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2c250 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2c260 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
2c270 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2c280 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
2c290 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
2c2a0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
2c2b0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
2c2c0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
2c2d0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
2c2e0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
2c2f0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
2c300 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
2c310 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
2c320 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
2c330 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2c340 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
2c350 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2c360 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
2c370 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
2c380 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2c390 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
2c3a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2c3b0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2c3c0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2c3d0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2c3e0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2c3f0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2c400 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2c410 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2c420 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2c430 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
2c440 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
2c450 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
2c460 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
2c470 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
2c480 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
2c490 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
2c4a0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
2c4b0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
2c4c0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2c4d0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
2c4e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2c4f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
2c500 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
2c510 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c520 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
2c530 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2c540 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2c550 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
2c560 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
2c570 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
2c580 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
2c590 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
2c5a0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2c5b0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
2c5c0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
2c5d0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
2c5e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
2c5f0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2c600 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
2c610 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2c620 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
2c630 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
2c640 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
2c650 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
2c660 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2c670 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
2c680 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
2c690 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
2c6a0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
2c6b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2c6c0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
2c6d0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
2c6e0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
2c6f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
2c700 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
2c710 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
2c720 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
2c730 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
2c740 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
2c750 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
2c760 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
2c770 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
2c780 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
2c790 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
2c7a0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
2c7b0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
2c7c0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
2c7d0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
2c7e0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
2c7f0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
2c800 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
2c810 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2c820 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
2c830 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
2c840 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
2c850 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
2c860 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2c870 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2c880 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
2c890 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2c8a0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
2c8b0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
2c8c0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
2c8d0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
2c8e0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2c8f0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
2c900 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
2c910 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2c920 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2c930 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
2c940 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2c950 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
2c960 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
2c970 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
2c980 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
2c990 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
2c9a0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
2c9b0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2c9c0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2c9d0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2c9e0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2c9f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2ca00 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
2ca10 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2ca20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ca30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2ca40 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2ca50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2ca60 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ca70 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2ca80 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2ca90 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2caa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2cab0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
2cac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2cad0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2cae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2caf0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
2cb00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2cb10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cb20 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2cb30 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2cb40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2cb50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
2cb60 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
2cb70 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
2cb80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2cb90 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2cba0 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2cbb0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2cbc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2cbd0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2cbe0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2cbf0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2cc00 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2cc10 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2cc20 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2cc30 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2cc40 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2cc50 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2cc60 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2cc70 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2cc80 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2cc90 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2cca0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2ccb0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2ccc0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2ccd0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2cce0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2ccf0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2cd00 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2cd10 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2cd20 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2cd30 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2cd40 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2cd50 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2cd60 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2cd70 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2cd80 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2cd90 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2cda0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2cdb0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2cdc0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2cdd0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2cde0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2cdf0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2ce00 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2ce10 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2ce20 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2ce30 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2ce40 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2ce50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ce60 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2ce70 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2ce80 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2ce90 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2cea0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2ceb0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2cec0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2ced0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2cee0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2cef0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2cf00 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2cf10 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2cf20 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2cf30 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2cf40 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2cf50 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2cf60 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2cf70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2cf80 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2cf90 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2cfa0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2cfb0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2cfc0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2cfd0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2cfe0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2cff0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2d000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d010 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2d020 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2d030 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d040 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2d050 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d060 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2d070 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2d080 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2d090 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d0a0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
2d0b0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
2d0c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
2d0d0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
2d0e0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
2d0f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d100 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2d110 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2d120 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
2d130 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2d140 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
2d150 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
2d160 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2d170 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
2d180 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
2d190 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
2d1a0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
2d1b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
2d1c0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
2d1d0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
2d1e0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2d1f0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
2d200 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
2d210 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
2d220 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
2d230 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
2d240 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
2d250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2d260 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
2d270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d280 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
2d290 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
2d2a0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
2d2b0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2d2c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d2d0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
2d2e0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
2d2f0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2d300 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2d310 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
2d320 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
2d330 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
2d340 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
2d350 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
2d360 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
2d370 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2d380 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
2d390 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
2d3a0 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
2d3b0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
2d3c0 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
2d3d0 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
2d3e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
2d3f0 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
2d400 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
2d410 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
2d420 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
2d430 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
2d440 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
2d450 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
2d460 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
2d470 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
2d480 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
2d490 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
2d4a0 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
2d4b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
2d4c0 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
2d4d0 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
2d4e0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2d4f0 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
2d500 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
2d510 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
2d520 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
2d530 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
2d540 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
2d550 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
2d560 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
2d570 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
2d580 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20  rs within an.** 
2d590 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2d5a0 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
2d5b0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
2d5c0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
2d5d0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
2d5e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
2d5f0 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
2d600 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
2d610 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
2d620 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
2d630 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
2d640 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2d650 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2d660 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
2d670 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2d680 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
2d690 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2d6a0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
2d6b0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
2d6c0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
2d6d0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2d6e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
2d6f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
2d700 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
2d710 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
2d720 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
2d730 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
2d740 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
2d750 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
2d760 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
2d770 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
2d780 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
2d790 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
2d7a0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
2d7b0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2d7c0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
2d7d0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
2d7e0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
2d7f0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
2d800 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
2d810 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
2d820 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
2d830 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
2d840 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
2d850 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
2d860 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
2d870 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2d880 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2d890 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
2d8a0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
2d8b0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
2d8c0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
2d8d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
2d8e0 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
2d8f0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2d900 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
2d910 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
2d920 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
2d930 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
2d940 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
2d950 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
2d960 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
2d970 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
2d980 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
2d990 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d9a0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
2d9b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d9c0 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
2d9d0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
2d9e0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2d9f0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
2da00 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2da10 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
2da20 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
2da30 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
2da40 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
2da50 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
2da60 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
2da70 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
2da80 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
2da90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2daa0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
2dab0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
2dac0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2dad0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
2dae0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
2daf0 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
2db00 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2db10 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
2db20 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
2db30 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
2db40 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
2db50 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2db60 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
2db70 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
2db80 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
2db90 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
2dba0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
2dbb0 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
2dbc0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
2dbd0 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
2dbe0 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
2dbf0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2dc00 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
2dc10 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
2dc20 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
2dc30 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
2dc40 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2dc50 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
2dc60 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
2dc70 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
2dc80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2dc90 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
2dca0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2dcb0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
2dcc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2dcd0 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
2dce0 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
2dcf0 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
2dd00 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
2dd10 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
2dd20 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33  r version 3.6.23
2dd30 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .1, sqlite3_step
2dd40 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
2dd50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2dd60 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
2dd70 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
2dd80 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
2dd90 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
2dda0 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
2ddb0 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
2ddc0 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
2ddd0 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
2dde0 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
2ddf0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
2de00 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
2de10 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
2de20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
2de30 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
2de40 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
2de50 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
2de60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2de70 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
2de80 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
2de90 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2dea0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
2deb0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
2dec0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
2ded0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2dee0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2def0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
2df00 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
2df10 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
2df20 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
2df30 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
2df40 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
2df50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
2df60 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
2df70 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
2df80 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
2df90 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2dfa0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
2dfb0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
2dfc0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
2dfd0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2dfe0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
2dff0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
2e000 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
2e010 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
2e020 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
2e030 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
2e040 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
2e050 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2e060 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
2e070 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
2e080 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
2e090 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
2e0a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2e0b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2e0c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e0d0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
2e0e0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
2e0f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2e100 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2e110 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
2e120 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
2e130 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2e140 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2e150 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
2e160 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
2e170 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
2e180 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
2e190 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2e1a0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
2e1b0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
2e1c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2e1d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e1e0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
2e1f0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
2e200 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2e210 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2e230 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2e240 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2e250 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2e260 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2e270 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2e280 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2e290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e2a0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2e2b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2e2c0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2e2d0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2e2e0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2e2f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2e300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2e310 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2e320 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2e330 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2e340 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2e350 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2e360 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2e370 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2e380 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2e390 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2e3a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2e3b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2e3c0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2e3d0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2e3e0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2e3f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2e400 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2e410 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2e420 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2e430 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2e440 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2e450 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2e460 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2e470 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2e480 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2e490 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2e4a0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2e4b0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2e4c0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2e4d0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2e4e0 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2e4f0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2e500 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2e510 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2e520 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2e530 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2e540 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2e550 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2e560 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2e570 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2e580 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2e590 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2e5a0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2e5b0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2e5c0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2e5d0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2e5e0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2e5f0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2e600 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2e610 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2e620 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2e630 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2e640 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2e650 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2e660 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2e670 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2e680 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2e690 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2e6a0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2e6b0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2e6c0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2e6d0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2e6e0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2e6f0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2e700 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2e710 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2e720 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2e730 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2e740 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2e750 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2e760 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2e770 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2e780 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2e790 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2e7a0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2e7b0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2e7c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2e7d0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2e7e0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2e7f0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2e800 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2e810 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2e820 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2e830 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2e840 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2e850 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2e860 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2e870 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2e880 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2e890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e8a0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2e8b0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2e8c0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2e8d0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2e8e0 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
2e8f0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e900 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2e910 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2e920 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
2e930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2e940 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2e950 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2e960 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2e970 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2e980 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2e990 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2e9a0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2e9b0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2e9c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2e9d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2e9e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2e9f0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2ea00 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2ea10 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2ea20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2ea30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ea40 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2ea50 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2ea60 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2ea70 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2ea80 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2ea90 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2eaa0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2eab0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2eac0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2ead0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2eae0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2eaf0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2eb00 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2eb10 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2eb20 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2eb30 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2eb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2eb50 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2eb60 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2eb70 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2eb80 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2eb90 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2eba0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2ebb0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2ebc0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2ebd0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2ebe0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2ebf0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2ec00 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2ec10 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2ec20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2ec30 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2ec40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2ec50 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2ec60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2ec70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2ec80 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2ec90 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2eca0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2ecb0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2ecc0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2ecd0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2ece0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2ecf0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2ed00 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2ed10 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2ed20 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2ed30 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2ed40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2ed50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2ed60 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2ed70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ed80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2ed90 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2eda0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2edb0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2edc0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2edd0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2ede0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2edf0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2ee00 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2ee10 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2ee20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ee30 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2ee40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ee50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2ee60 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2ee70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2ee80 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2ee90 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2eea0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2eeb0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2eec0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2eed0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2eee0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2eef0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2ef00 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2ef10 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2ef20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2ef30 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2ef40 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2ef50 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2ef60 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2ef70 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2ef80 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2ef90 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2efa0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2efb0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2efc0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2efd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2efe0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2eff0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2f000 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2f010 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2f020 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2f030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f040 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2f050 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f060 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2f070 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2f080 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2f090 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2f0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f0b0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2f0c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f0d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2f0e0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2f0f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2f100 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2f110 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2f120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f130 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2f140 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2f150 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2f160 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2f170 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2f180 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2f190 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2f1a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f1b0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2f1c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2f1d0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2f1e0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2f1f0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2f200 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2f210 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f220 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2f230 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2f240 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2f250 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f260 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2f270 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2f280 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f290 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2f2a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2f2b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f2c0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2f2d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f2e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f2f0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2f300 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2f310 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f320 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2f330 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f340 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2f350 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2f360 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2f370 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2f380 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f390 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2f3a0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2f3b0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2f3c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f3d0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2f3e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2f3f0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2f400 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2f410 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2f420 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2f430 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f440 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2f450 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f460 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2f470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f480 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2f490 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2f4a0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2f4b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2f4c0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2f4d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2f4e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2f4f0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2f500 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2f510 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2f520 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2f530 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2f540 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2f550 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2f560 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f570 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2f580 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f590 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2f5a0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2f5b0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2f5c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2f5d0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2f5e0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2f5f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f600 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2f610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f620 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2f630 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2f640 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2f650 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2f660 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2f670 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2f680 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2f690 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2f6a0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2f6b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2f6c0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2f6d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2f6e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2f6f0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2f700 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f710 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
2f720 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f730 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
2f740 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
2f750 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2f760 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
2f770 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2f780 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
2f790 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
2f7a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f7b0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
2f7c0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2f7d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2f7e0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
2f7f0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
2f800 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
2f810 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2f820 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2f830 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
2f840 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2f850 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2f860 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
2f870 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2f880 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2f890 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2f8a0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
2f8b0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2f8c0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
2f8d0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
2f8e0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
2f8f0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
2f900 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
2f910 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
2f920 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
2f930 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f940 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
2f950 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
2f960 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
2f970 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
2f980 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
2f990 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
2f9a0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
2f9b0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
2f9c0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
2f9d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2f9e0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2f9f0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
2fa00 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
2fa10 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
2fa20 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
2fa30 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
2fa40 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2fa50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2fa60 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
2fa70 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2fa80 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2fa90 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2faa0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
2fab0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2fac0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
2fad0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
2fae0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2faf0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2fb00 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2fb10 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
2fb20 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2fb30 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2fb40 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2fb50 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
2fb60 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
2fb70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2fb80 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
2fb90 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2fba0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2fbb0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2fbc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2fbd0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2fbe0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
2fbf0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2fc00 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2fc10 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2fc20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2fc30 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
2fc40 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2fc50 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2fc60 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2fc70 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2fc80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2fc90 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2fca0 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
2fcb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2fcc0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
2fcd0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
2fce0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
2fcf0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2fd00 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2fd10 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
2fd20 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
2fd30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
2fd40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
2fd50 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
2fd60 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2fd70 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2fd80 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2fd90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2fda0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
2fdb0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
2fdc0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
2fdd0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2fde0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2fdf0 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
2fe00 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
2fe10 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
2fe20 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
2fe30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
2fe40 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
2fe50 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
2fe60 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
2fe70 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
2fe80 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
2fe90 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
2fea0 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
2feb0 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
2fec0 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
2fed0 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
2fee0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
2fef0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
2ff00 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
2ff10 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
2ff20 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
2ff30 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
2ff40 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
2ff50 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
2ff60 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
2ff70 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
2ff80 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
2ff90 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
2ffa0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
2ffb0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2ffc0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2ffd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ffe0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
2fff0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30000 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
30010 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
30020 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
30030 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
30040 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
30050 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
30060 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
30070 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
30080 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
30090 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
300a0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
300b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
300c0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
300d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
300e0 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
300f0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
30100 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
30110 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
30120 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
30130 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
30140 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
30150 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
30160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30170 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
30180 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30190 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
301a0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
301b0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
301c0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
301d0 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</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 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
30210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30220 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
30230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30240 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
30250 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
30260 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
30270 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
30280 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
30290 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
302a0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
302b0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
302c0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
302d0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
302e0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
302f0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
30300 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
30310 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
30320 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
30330 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
30340 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
30350 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
30360 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
30370 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
30380 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
30390 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
303a0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
303b0 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
303c0 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
303d0 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
303e0 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
303f0 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
30400 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
30410 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
30420 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
30430 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
30440 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
30450 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
30460 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
30470 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
30480 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
30490 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
304a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
304b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
304c0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
304d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
304e0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
304f0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30500 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
30510 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
30520 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
30530 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30540 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30550 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
30560 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
30570 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
30580 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
30590 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
305a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
305b0 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
305c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
305d0 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
305e0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
305f0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
30600 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
30610 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
30620 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
30630 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
30640 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
30650 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
30660 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
30670 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
30680 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
30690 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
306a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
306b0 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
306c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
306d0 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
306e0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
306f0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
30700 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
30710 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
30720 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30730 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
30740 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
30750 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
30760 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
30770 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
30780 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
30790 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
307a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
307b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
307c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
307d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
307e0 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
307f0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
30800 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
30810 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
30820 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
30830 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
30840 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
30850 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
30860 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
30870 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
30880 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30890 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
308a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
308b0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
308c0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
308d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
308e0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
308f0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
30900 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
30910 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
30920 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
30930 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
30940 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
30950 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
30960 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
30970 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
30980 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
30990 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
309a0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
309b0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
309c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
309d0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
309e0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
309f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30a00 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
30a10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
30a20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
30a30 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
30a40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30a50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
30a60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
30a70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30a80 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
30a90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
30aa0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
30ab0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30ac0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30ad0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
30ae0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
30af0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
30b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
30b10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30b20 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
30b30 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
30b40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30b50 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
30b60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
30b70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30b80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30b90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30ba0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30bb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
30bc0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
30bd0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
30be0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
30bf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
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 0a 2f 2a 0a 2a  int iCol);../*.*
30c20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
30c30 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
30c40 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
30c50 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
30c60 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
30c80 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
30c90 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
30ca0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
30cb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
30cc0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
30cd0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
30ce0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
30cf0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
30d00 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
30d10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30d20 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
30d30 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
30d40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
30d50 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
30d60 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
30d70 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
30d80 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
30d90 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
30da0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
30db0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
30dc0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
30dd0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
30de0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
30df0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
30e00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
30e10 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
30e20 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
30e30 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
30e40 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
30e50 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
30e60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
30e70 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
30e80 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
30e90 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
30ea0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
30eb0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
30ec0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
30ed0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
30ee0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30ef0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
30f00 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
30f10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
30f20 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
30f30 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
30f40 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
30f50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
30f60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
30f70 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
30f80 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
30f90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
30fa0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
30fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30fc0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
30fd0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
30fe0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
30ff0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
31000 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
31010 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
31020 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
31030 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
31040 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
31050 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
31060 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
31070 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
31080 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
31090 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
310a0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
310b0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
310c0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
310d0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
310e0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
310f0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
31100 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
31110 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
31120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31130 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
31140 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
31150 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
31160 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31170 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31180 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
31190 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
311a0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
311b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
311c0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
311d0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
311e0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
311f0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
31200 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
31210 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
31220 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
31230 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
31240 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
31250 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
31260 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
31270 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
31280 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
31290 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
312a0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
312b0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
312c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
312d0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
312e0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
312f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31300 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
31310 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
31320 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
31330 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
31340 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
31350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
31360 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
31370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31380 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
31390 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
313a0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
313b0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
313c0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
313d0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
313e0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
313f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
31400 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
31410 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
31420 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
31430 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
31440 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
31450 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
31460 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
31470 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
31480 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
31490 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
314a0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
314b0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
314c0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
314d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
314e0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
314f0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
31500 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
31510 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
31520 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
31530 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31540 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
31550 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
31560 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
31570 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31580 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
31590 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
315a0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
315b0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
315c0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
315d0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
315e0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
315f0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
31600 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
31610 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
31620 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
31630 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
31640 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
31650 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
31660 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
31670 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
31680 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
31690 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
316a0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
316b0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
316c0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
316d0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
316e0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
316f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
31700 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
31710 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
31720 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
31730 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
31740 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
31750 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
31760 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
31770 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
31780 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
31790 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
317a0 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
317b0 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
317c0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
317d0 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
317e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
317f0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
31800 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
31810 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
31820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31830 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
31840 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
31850 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
31860 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
31870 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
31880 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
31890 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
318a0 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
318b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
318c0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
318d0 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
318e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
318f0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
31900 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
31910 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31920 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
31930 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
31940 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
31950 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
31960 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
31970 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
31980 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
31990 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
319a0 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
319b0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
319c0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
319d0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
319e0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
319f0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
31a00 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
31a10 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
31a20 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
31a30 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
31a40 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
31a50 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
31a60 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
31a70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
31a80 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
31a90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
31aa0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
31ab0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
31ac0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31ad0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
31ae0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31af0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
31b00 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31b10 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
31b20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
31b30 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
31b40 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
31b50 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
31b60 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
31b70 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
31b80 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
31b90 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
31ba0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
31bb0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
31bc0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
31bd0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
31be0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
31bf0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
31c00 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
31c10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
31c20 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
31c30 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
31c40 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
31c50 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
31c60 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
31c70 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
31c80 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
31c90 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
31ca0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
31cb0 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
31cc0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
31cd0 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
31ce0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31cf0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
31d00 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
31d10 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
31d20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
31d30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
31d40 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
31d50 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
31d60 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
31d70 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
31d80 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
31d90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
31da0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31db0 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
31dc0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
31dd0 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
31de0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
31df0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
31e00 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
31e10 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
31e20 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
31e30 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31e40 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
31e50 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
31e60 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
31e70 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
31e80 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
31e90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31ea0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
31eb0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
31ec0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
31ed0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
31ee0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
31ef0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
31f00 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
31f10 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
31f20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
31f30 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
31f40 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
31f50 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
31f60 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
31f70 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
31f80 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
31f90 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
31fa0 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
31fb0 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
31fc0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
31fd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
31fe0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
31ff0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
32000 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
32010 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
32020 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
32030 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
32040 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
32050 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
32060 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
32070 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
32080 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
32090 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
320a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
320b0 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
320c0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
320d0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
320e0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
320f0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
32100 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
32110 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
32120 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
32130 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
32140 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
32150 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32160 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
32170 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
32180 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
32190 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
321a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
321b0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
321c0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
321d0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
321e0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
321f0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
32200 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
32210 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
32220 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
32230 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
32240 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32250 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
32260 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32270 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32280 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
32290 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
322a0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
322b0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
322c0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
322d0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
322e0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
322f0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
32300 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
32310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32320 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
32330 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
32340 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
32350 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
32360 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
32370 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
32380 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
32390 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
323a0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
323b0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
323c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
323d0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
323e0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
323f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32400 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
32410 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
32420 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
32430 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
32440 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
32450 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
32460 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
32470 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
32480 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
32490 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
324a0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
324b0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
324c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
324d0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
324e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
324f0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
32500 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
32510 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32520 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
32530 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
32540 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
32550 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
32560 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
32570 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
32580 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
32590 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
325a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
325b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
325c0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
325d0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
325e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
325f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32600 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
32610 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
32620 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
32630 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
32640 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
32650 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
32660 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
32670 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
32680 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
32690 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
326a0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
326b0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
326c0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
326d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
326e0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
326f0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
32700 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
32710 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
32720 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
32730 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
32740 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32750 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
32760 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
32770 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
32780 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
32790 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
327a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
327b0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
327c0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
327d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
327e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
327f0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
32800 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
32810 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
32820 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
32830 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
32840 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
32850 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
32860 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
32870 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
32880 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
32890 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
328a0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
328b0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
328c0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
328d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
328e0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
328f0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
32900 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
32910 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
32920 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
32930 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
32940 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32950 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
32960 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
32970 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32980 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
32990 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
329a0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
329b0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
329c0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
329d0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
329e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
329f0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
32a00 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
32a10 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
32a20 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
32a30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
32a40 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
32a50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32a60 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
32a70 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
32a80 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
32a90 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32aa0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32ab0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32ac0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32ad0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32ae0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32af0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32b00 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32b10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32b20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32b30 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
32b40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
32b50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32b60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32b70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32b80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
32b90 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
32ba0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
32bb0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
32bc0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
32bd0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
32be0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32bf0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32c00 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
32c10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32c20 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32c30 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32c40 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
32c50 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
32c60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32c70 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
32c80 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32c90 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
32ca0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32cb0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32cc0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32cd0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32ce0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32cf0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32d00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32d10 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
32d20 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32d30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32d40 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
32d50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32d60 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
32d70 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
32d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32d90 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
32da0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32db0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
32dc0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
32dd0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
32de0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
32df0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
32e00 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
32e10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32e20 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
32e30 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
32e40 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
32e50 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
32e60 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
32e70 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
32e80 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
32e90 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
32ea0 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
32eb0 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
32ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32ed0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
32ee0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
32ef0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
32f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32f10 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
32f20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
32f30 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
32f40 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
32f50 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
32f60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32f70 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
32f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
32f90 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
32fa0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
32fb0 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
32fc0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
32fd0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
32fe0 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
32ff0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
33000 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
33010 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
33020 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33030 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
33040 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33050 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33060 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33070 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
33080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
33090 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
330a0 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
330b0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
330c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
330d0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
330e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
330f0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
33100 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
33110 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
33120 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
33130 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
33140 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
33150 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
33160 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
33170 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
33180 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
33190 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
331a0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
331b0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
331c0 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
331d0 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
331e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
331f0 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
33200 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
33210 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
33220 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
33230 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
33240 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
33250 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
33260 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33270 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
33280 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33290 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
332a0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
332b0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
332c0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
332d0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
332e0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
332f0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
33300 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
33310 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
33320 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
33330 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
33340 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
33350 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
33360 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
33370 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33380 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
33390 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
333a0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
333b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
333c0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
333d0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
333e0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
333f0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
33400 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
33410 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  ter Values.** ME
33420 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
33430 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  lue.**.** The C-
33440 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
33450 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
33460 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33470 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
33480 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
33490 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
334a0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
334b0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
334c0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
334d0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
334e0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
334f0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
33500 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
33510 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
33520 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
33530 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33540 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
33550 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33560 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
33570 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
33580 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
33590 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
335a0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
335b0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
335c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
335d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
335e0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
335f0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
33600 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
33610 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
33620 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
33630 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33640 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
33650 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
33660 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
33670 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
33680 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
33690 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
336a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
336b0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
336c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
336d0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
336e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
336f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33700 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
33710 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
33720 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
33730 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33740 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
33750 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
33760 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
33770 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
33780 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
33790 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
337a0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
337b0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
337c0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
337d0 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
337e0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
337f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
33800 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33810 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
33820 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
33830 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
33840 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
33850 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
33860 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33870 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
33880 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
33890 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
338a0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
338b0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
338c0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
338d0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
338e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
338f0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
33900 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33910 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
33920 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
33930 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
33940 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
33950 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
33960 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
33970 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
33980 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
33990 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
339a0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
339b0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
339c0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
339d0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
339e0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
339f0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
33a00 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
33a10 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
33a20 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
33a30 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
33a40 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
33a50 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
33a60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
33a70 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
33a80 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
33a90 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
33aa0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
33ab0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
33ac0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
33ad0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
33ae0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
33af0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
33b00 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
33b10 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
33b20 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
33b30 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
33b40 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
33b50 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
33b60 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
33b70 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
33b80 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
33b90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33ba0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
33bb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
33bc0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33bd0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
33be0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
33bf0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
33c00 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
33c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33c20 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
33c30 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
33c40 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
33c50 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
33c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33c70 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
33c80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
33c90 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
33ca0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
33cb0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
33cc0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
33cd0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
33ce0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
33cf0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
33d00 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33d10 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
33d20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33d30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33d40 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
33d50 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
33d60 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
33d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33d80 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
33d90 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
33da0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
33db0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
33dc0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
33dd0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
33de0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
33df0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
33e00 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
33e10 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
33e20 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
33e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33e40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
33e50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33e60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33e70 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
33e80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33e90 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
33ea0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
33eb0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
33ec0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
33ed0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
33ee0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
33ef0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33f00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
33f10 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
33f20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33f30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33f40 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
33f50 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
33f60 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  text.** METHOD: 
33f70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
33f80 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
33f90 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
33fa0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
33fb0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
33fc0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
33fd0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
33fe0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
33ff0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
34000 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
34010 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34020 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
34030 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
34040 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
34050 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34060 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
34070 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
34080 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
34090 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
340a0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
340b0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
340c0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
340d0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
340e0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
340f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34100 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
34110 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
34120 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
34130 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
34140 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
34150 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
34160 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34170 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
34180 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
34190 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
341a0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
341b0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
341c0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
341d0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
341e0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
341f0 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
34200 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
34210 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
34220 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
34230 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
34240 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
34250 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
34260 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
34270 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
34280 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
34290 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
342a0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
342b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
342c0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
342d0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
342e0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
342f0 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
34300 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
34310 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
34320 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
34330 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34340 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34350 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
34360 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
34370 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
34380 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
34390 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
343a0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
343b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
343c0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
343d0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
343e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
343f0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
34400 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
34410 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
34420 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
34430 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
34440 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
34450 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
34460 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
34470 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34480 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
34490 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
344a0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
344b0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
344c0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
344d0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
344e0 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
344f0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
34500 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
34510 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
34520 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
34530 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34540 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
34550 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
34560 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
34570 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
34580 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
34590 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
345a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
345b0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
345c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
345d0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
345e0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
345f0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
34600 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34610 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
34620 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
34630 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
34640 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
34650 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
34660 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
34670 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
34680 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34690 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
346a0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
346b0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
346c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
346d0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
346e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
346f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
34700 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
34710 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
34720 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
34730 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
34740 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34750 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
34760 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
34770 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34780 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
34790 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
347a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
347b0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
347c0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
347d0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
347e0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
347f0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
34800 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
34810 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
34820 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
34830 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
34840 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34850 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
34860 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
34870 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
34880 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
34890 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
348a0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
348b0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
348c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
348d0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
348e0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
348f0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
34900 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
34910 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34920 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
34930 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
34940 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
34950 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
34960 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
34970 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
34980 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
34990 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
349a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
349b0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
349c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
349d0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
349e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
349f0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
34a00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
34a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34a20 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
34a30 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
34a40 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
34a50 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
34a60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34a70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34a80 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
34a90 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
34aa0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
34ab0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
34ac0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
34ad0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
34ae0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
34af0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
34b00 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
34b10 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
34b20 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
34b30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34b40 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
34b50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
34b60 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
34b70 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
34b80 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
34b90 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
34ba0 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
34bb0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
34bc0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
34bd0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
34be0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
34bf0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
34c00 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
34c10 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
34c20 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
34c30 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
34c40 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
34c50 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
34c60 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
34c70 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
34c80 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
34c90 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
34ca0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
34cb0 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e   matching.** fun
34cc0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
34cd0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
34ce0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
34cf0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f  ssion can be sto
34d00 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
34d10 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
34d20 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  th the pattern s
34d30 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e  tring.  .** Then
34d40 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
34d50 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72  pattern string r
34d60 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c  emains the same,
34d70 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  .** the compiled
34d80 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
34d90 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
34da0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
34db0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
34dc0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
34dd0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
34de0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
34df0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
34e00 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
34e10 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
34e20 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
34e30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
34e40 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
34e50 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
34e60 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
34e70 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
34e80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34e90 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72  nction. ^If ther
34ea0 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
34eb0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
34ec0 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ith the function
34ed0 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20   argument, this 
34ee0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
34ef0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ata() interface.
34f00 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ** returns a NUL
34f10 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
34f20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
34f30 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
34f40 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  X) interface sav
34f50 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61  es P as metadata
34f60 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
34f70 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
34f80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34f90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
34fa0 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63  ^Subsequent.** c
34fb0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
34fc0 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
34fd0 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74   return P from t
34fe0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
34ff0 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
35000 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63  xdata(C,N,P,X) c
35010 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64  all if the metad
35020 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c  ata is still val
35030 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66  id or.** NULL if
35040 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61   the metadata ha
35050 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64  s been discarded
35060 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68  ..** ^After each
35070 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35080 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
35090 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73  ,P,X) where X is
350a0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51   not NULL,.** SQ
350b0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
350c0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
350d0 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20  function X with 
350e0 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63  parameter P exac
350f0 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65  tly.** once, whe
35100 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  n the metadata i
35110 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  s discarded..** 
35120 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
35130 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65  o discard the me
35140 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69  tadata at any ti
35150 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c  me, including: <
35160 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e  ul>.** <li> when
35170 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
35180 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
35190 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f  meter changes, o
351a0 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b  r.** <li> when [
351b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
351c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
351d0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
351e0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ed for the.**   
351f0 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
35200 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
35210 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  n sqlite3_set_au
35220 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b  xdata() is invok
35230 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20  ed again on the 
35240 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  same parameter, 
35250 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e  or.** <li> durin
35260 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  g the original s
35270 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35280 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61  ta() call when a
35290 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20   memory .**     
352a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
352b0 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29  r occurs. </ul>)
352c0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65  ^.**.** Note the
352d0 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20   last bullet in 
352e0 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65  particular.  The
352f0 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e   destructor X in
35300 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74   .** sqlite3_set
35310 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
35320 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
35330 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  d immediately, b
35340 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c  efore the.** sql
35350 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35360 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65  () interface eve
35370 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63  n returns.  Henc
35380 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
35390 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c  xdata().** shoul
353a0 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72  d be called near
353b0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
353c0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
353d0 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a  ntation and the.
353e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ** function impl
353f0 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
35400 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75  d not make any u
35410 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a  se of P after.**
35420 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35430 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20  data() has been 
35440 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  called..**.** ^(
35450 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
35460 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
35470 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
35480 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
35490 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
354a0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f  ters that are co
354b0 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74  mpile-time const
354c0 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ants, including 
354d0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
354e0 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
354f0 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f  s] and expressio
35500 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d  ns composed from
35510 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a   the same.)^.**.
35520 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
35530 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
35540 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
35550 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
35560 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
35570 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
35580 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
35590 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
355a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
355b0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
355c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
355d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
355e0 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
355f0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
35600 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
35610 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
35620 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
35630 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
35640 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
35650 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
35660 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
35670 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
35680 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
35690 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
356a0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
356b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
356c0 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
356d0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
356e0 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
356f0 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
35700 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
35710 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
35720 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
35730 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
35740 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
35750 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
35760 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
35770 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
35780 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
35790 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
357a0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
357b0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
357c0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
357d0 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
357e0 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
357f0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
35800 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
35810 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
35820 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
35830 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
35840 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
35850 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
35860 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a  C++ compilers..*
35870 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
35880 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
35890 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
358a0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
358b0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
358c0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
358d0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
358e0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
358f0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
35900 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
35910 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
35920 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
35930 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
35940 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54   Function.** MET
35950 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
35960 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
35970 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
35980 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
35990 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
359a0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
359b0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
359c0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
359d0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
359e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
359f0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
35a00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35a10 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
35a20 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
35a30 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
35a40 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
35a50 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
35a60 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
35a70 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
35a80 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
35a90 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
35aa0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
35ab0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
35ac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
35ad0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
35ae0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
35af0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
35b00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
35b10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
35b20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35b30 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
35b40 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35b50 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
35b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35b70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35b80 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
35b90 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
35ba0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
35bb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
35bc0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
35bd0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
35be0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
35bf0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
35c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35c10 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
35c20 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
35c30 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
35c40 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
35c50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35c60 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
35c70 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
35c80 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
35c90 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
35ca0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
35cb0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
35cc0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
35cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35ce0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
35cf0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
35d00 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
35d10 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
35d20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35d30 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
35d40 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
35d50 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
35d60 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
35d70 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35d80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35d90 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
35da0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35db0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
35dc0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
35dd0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
35de0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
35df0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
35e00 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
35e10 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
35e20 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
35e30 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
35e40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35e50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
35e60 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
35e70 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
35e80 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
35e90 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
35ea0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
35eb0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
35ec0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
35ed0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
35ee0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
35ef0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
35f00 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
35f10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35f20 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
35f30 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
35f40 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
35f50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
35f60 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
35f70 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
35f80 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35f90 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
35fa0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
35fb0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
35fc0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
35fd0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
35fe0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
35ff0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
36000 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
36010 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
36020 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36030 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
36040 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36050 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
36060 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
36070 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
36080 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
36090 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
360a0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
360b0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
360c0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
360d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
360e0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
360f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36100 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
36110 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
36120 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
36130 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
36140 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
36150 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
36160 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
36170 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
36180 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
36190 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
361a0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
361b0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
361c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
361d0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
361e0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
361f0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
36200 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
36210 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
36220 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
36230 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
36240 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
36250 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
36260 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
36270 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
36280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36290 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
362a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
362b0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
362c0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
362d0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
362e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
362f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
36300 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
36310 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
36320 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
36330 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
36340 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
36350 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
36360 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
36370 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36380 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
36390 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
363a0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
363b0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
363c0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
363d0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
363e0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
363f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36400 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
36410 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36420 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36430 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36440 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36450 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36460 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
36470 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36480 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36490 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
364a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
364b0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
364c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
364d0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
364e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
364f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36500 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
36510 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
36520 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
36530 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
36540 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36550 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
36560 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() 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 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
365c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
365d0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
365e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
365f0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
36600 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
36610 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
36620 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
36630 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
36640 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36650 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
36660 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36670 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
36680 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
36690 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
366a0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
366b0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
366c0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
366d0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
366e0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
366f0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
36700 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  y..** ^The sqlit
36710 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
36720 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36730 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
36740 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c  ue of an.** appl
36750 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36760 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
36770 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20   text string in 
36780 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73  an encoding.** s
36790 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
367a0 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29  fifth (and last)
367b0 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
367c0 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a  h must be one.**
367d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
367e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
367f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
36800 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
36810 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51  UTF16LE]..** ^SQ
36820 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
36830 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
36840 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
36850 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
36860 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
36870 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36880 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
36890 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
368a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
368b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
368c0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
368d0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
368e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
368f0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
36900 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
36910 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
36920 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
36930 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
36940 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
36950 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
36960 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36970 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
36980 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
36990 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
369a0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
369b0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
369c0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
369d0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
369e0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
369f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36a00 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
36a10 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
36a20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
36a30 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
36a40 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
36a50 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
36a60 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
36a70 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
36a80 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
36a90 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
36aa0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
36ab0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
36ac0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
36ad0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
36ae0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
36af0 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
36b00 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
36b10 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
36b20 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
36b30 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
36b40 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
36b50 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
36b60 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
36b70 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
36b80 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
36b90 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
36ba0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
36bb0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
36bc0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
36bd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36be0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36bf0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36c00 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
36c10 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
36c20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
36c30 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
36c40 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
36c50 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
36c60 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
36c70 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
36c80 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
36c90 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
36ca0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
36cb0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
36cc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
36cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36ce0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
36cf0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
36d00 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
36d10 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
36d20 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
36d30 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
36d40 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
36d50 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
36d60 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
36d70 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
36d80 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
36d90 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
36da0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
36db0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
36dc0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
36dd0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
36de0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
36df0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
36e00 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
36e10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36e20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36e30 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
36e40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
36e50 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
36e60 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
36e70 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
36e80 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
36e90 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
36ea0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
36eb0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
36ec0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
36ed0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
36ee0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
36ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
36f10 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
36f20 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
36f30 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
36f40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36f50 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
36f60 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
36f70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36f80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
36f90 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
36fa0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
36fb0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
36fc0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
36fd0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
36fe0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
36ff0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
37000 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
37010 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
37020 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
37030 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
37040 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
37050 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
37060 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
37070 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
37080 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
37090 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
370a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
370b0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
370c0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
370d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
370e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
370f0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
37100 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
37110 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
37120 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
37130 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
37140 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
37150 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
37160 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
37170 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
37180 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
37190 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
371a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
371b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
371c0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
371d0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
371e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
371f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
37200 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
37210 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
37220 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37230 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37240 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
37250 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
37260 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
37270 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34  e3_result_blob64
37280 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37290 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20  *,const void*,. 
372a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
372b0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
372c0 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29  3_uint64,void(*)
372d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
372e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
372f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
37300 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
37310 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37320 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
37330 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37340 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
37350 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37360 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
37370 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37380 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
37390 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
373a0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
373b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
373c0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
373d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
373e0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
373f0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
37400 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37410 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
37420 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
37430 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37440 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
37450 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
37460 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37470 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
37480 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
37490 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
374a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
374b0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
374c0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
374d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
374e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
374f0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
37500 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
37510 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
37520 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73  _result_text64(s
37530 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37540 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c   const char*,sql
37550 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
37560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37570 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
37580 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
37590 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
375a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
375b0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
375c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
375d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
375e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
375f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37600 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
37610 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37620 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37630 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
37640 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37650 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
37660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37670 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
37680 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
37690 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
376a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
376b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
376c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
376d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
376e0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
376f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
37700 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
37710 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
37720 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
37730 75 65 6e 63 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  uences.** METHOD
37740 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
37750 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
37760 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
37770 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
37780 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
37790 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
377a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
377b0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
377c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
377d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
377e0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
377f0 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
37800 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
37810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37820 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
37830 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37840 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
37850 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
37860 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
37870 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
37880 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37890 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
378a0 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
378b0 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
378c0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
378d0 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
378e0 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
378f0 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
37900 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
37910 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
37920 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
37930 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
37940 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
37950 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
37960 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
37970 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
37980 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
37990 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
379a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
379b0 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
379c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
379d0 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
379e0 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
379f0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
37a00 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
37a10 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
37a20 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
37a30 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
37a40 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
37a50 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
37a60 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
37a70 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
37a80 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
37a90 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
37aa0 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
37ab0 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
37ac0 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
37ad0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
37ae0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
37af0 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
37b00 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
37b10 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
37b20 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
37b30 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
37b40 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
37b50 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
37b60 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
37b70 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
37b80 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
37b90 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
37ba0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
37bb0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
37bc0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
37bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
37be0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
37bf0 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
37c00 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
37c10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
37c20 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
37c30 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
37c40 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
37c50 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
37c60 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
37c70 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
37c80 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
37c90 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
37ca0 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
37cb0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
37cc0 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
37cd0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
37ce0 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
37cf0 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
37d00 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
37d10 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
37d20 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
37d30 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
37d40 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
37d50 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
37d60 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
37d70 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
37d80 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
37d90 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
37da0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
37db0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37dc0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
37dd0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
37de0 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
37df0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
37e00 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
37e10 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
37e20 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
37e30 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
37e40 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
37e50 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
37e60 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37e70 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
37e80 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
37e90 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
37ea0 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
37eb0 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
37ec0 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
37ed0 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
37ee0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
37ef0 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
37f00 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
37f10 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37f20 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
37f30 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
37f40 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
37f50 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
37f60 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
37f70 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37f80 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
37f90 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
37fa0 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
37fb0 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
37fc0 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
37fd0 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
37fe0 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
37ff0 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
38000 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
38010 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
38020 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
38030 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
38040 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
38050 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
38060 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
38070 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
38080 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
38090 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
380a0 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
380b0 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
380c0 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
380d0 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
380e0 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
380f0 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
38100 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
38110 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
38120 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
38130 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
38140 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
38150 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
38160 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
38170 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
38180 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
38190 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
381a0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
381b0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
381c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
381d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
381e0 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
381f0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
38200 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
38210 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
38220 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
38230 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
38240 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
38250 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
38260 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38270 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
38280 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
38290 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
382a0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
382b0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
382c0 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
382d0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
382e0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
382f0 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
38300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38310 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
38320 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
38330 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
38340 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
38350 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
38360 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
38370 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
38380 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
38390 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
383a0 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
383b0 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
383c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
383d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
383e0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
383f0 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
38400 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
38410 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
38420 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
38430 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38440 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
38450 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
38460 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
38470 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
38480 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
38490 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
384a0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
384b0 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
384c0 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
384d0 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
384e0 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
384f0 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
38500 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
38510 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
38520 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
38530 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
38540 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
38550 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
38560 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
38570 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38580 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
38590 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
385a0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
385b0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
385c0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
385d0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
385e0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
385f0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
38600 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
38610 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
38620 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
38630 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38640 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
38650 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
38660 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
38670 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
38680 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
38690 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
386a0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
386b0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
386c0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
386d0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
386e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
386f0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
38700 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
38710 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
38720 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
38730 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
38740 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
38750 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
38760 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
38770 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
38780 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
38790 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
387a0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
387b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
387c0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
387d0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
387e0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
387f0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
38800 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
38810 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
38820 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
38830 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
38840 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
38850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38860 6f 6e 5d 20 74 6f 20 62 65 20 69