System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact ddeef646e024ac15629ff495b11fc7373a9f6c87:


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 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 38 2e 37 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.7".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 38 30 30 37 0a 23 64 65 66  BER 3008007.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 34 2d  E_ID      "2014-
1070: 31 30 2d 30 38 20 31 35 3a 35 33 3a 32 31 20 36  10-08 15:53:21 6
1080: 34 38 33 64 34 32 36 63 34 63 35 63 37 37 32 63  483d426c4c5c772c
1090: 64 34 39 34 31 32 65 61 33 37 65 30 66 61 37 61  d49412ea37e0fa7a
10a0: 30 33 37 38 39 30 34 22 0a 0a 2f 2a 0a 2a 2a 20  0378904"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1c70: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1c80: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1c90: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1ca0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1cb0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1cc0: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1cd0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1ce0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1cf0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1d00: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1d10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1d20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1d30: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1d40: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1d50: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1d60: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1d70: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1d80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1d90: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1da0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1db0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1dc0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1dd0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1de0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1df0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1e00: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1e10: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1e20: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1e30: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1e40: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1e50: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1e60: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1e70: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
1e80: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
1e90: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
1ea0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
1eb0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
1ec0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
1ed0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
1ee0: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1ef0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
1f00: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
1f10: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
1f20: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f30: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
1f40: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
1f50: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
1f60: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
1f70: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
1f80: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
1f90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1fa0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
1fb0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
1fc0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fd0: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
1fe0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
1ff0: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2000: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2010: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
2020: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2030: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
2040: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2050: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2060: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
2070: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
2080: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
2090: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
20a0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
20b0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
20c0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
20d0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
20f0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2110: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
2120: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2130: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2150: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
2160: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2170: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
2180: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
2190: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
21a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
21b0: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
21c0: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
21d0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
21e0: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
21f0: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
2200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
2210: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2220: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2230: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
2240: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
2250: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
2260: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2270: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
2280: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
2290: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
22a0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
22b0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
22c0: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
22d0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
22e0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
22f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2300: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2310: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
2320: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
2330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
2340: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2350: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
2360: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
2370: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
2380: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
2390: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
23a0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
23b0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
23c0: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
23d0: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
23e0: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
23f0: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
2400: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
2410: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2420: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2430: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
2440: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2450: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
2460: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
2470: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
2480: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
2490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
24a0: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
24b0: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
24c0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
24d0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
24e0: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
24f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2500: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2510: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2530: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
2540: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
2550: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
2560: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
2570: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
2580: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2590: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
25a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25b0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
25c0: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
25d0: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
25e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
25f0: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
2600: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
2610: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
2620: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
2630: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
2640: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
2650: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
2660: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
2670: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
2680: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2690: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
26a0: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
26b0: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
26c0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
26d0: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
26e0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
26f0: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
2700: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
2710: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
2720: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
2730: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2740: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2750: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
2760: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2770: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
2780: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
2790: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
27a0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
27b0: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
27c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
27d0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
27e0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
27f0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2800: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
2810: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
2820: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
2830: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
2840: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2850: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
2860: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2870: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2880: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
2890: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28b0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
28c0: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
28d0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
28e0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
28f0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2900: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2910: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2920: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2930: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2940: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2950: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2960: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2970: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2980: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2990: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
29a0: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
29b0: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
29c0: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
29d0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
29e0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
29f0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2a00: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2a10: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2a20: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2a30: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2a40: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2a50: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2a60: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2a70: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2a80: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2a90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2aa0: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2ab0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2ac0: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
2ad0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2ae0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2af0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2b00: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2b10: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2b20: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2b30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b40: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2b50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2b60: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2b70: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2b80: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2b90: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ba0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2bb0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2bc0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2bd0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2be0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2bf0: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2c00: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2c10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2c20: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2c30: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2c40: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2c50: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2c60: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2c70: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2c80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2c90: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2ca0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2cb0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2cc0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2cd0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2ce0: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2cf0: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2d00: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2d10: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2d20: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2d30: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2d40: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2d50: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2d60: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2d70: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2d80: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2d90: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2da0: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2db0: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2dc0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2dd0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2de0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2df0: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2e00: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2e10: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2e20: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2e30: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2e40: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2e50: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2e60: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2e70: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2e80: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2e90: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
2ea0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
2eb0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2ec0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
2ed0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
2ee0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2ef0: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
2f00: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
2f10: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
2f20: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
2f30: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
2f40: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
2f50: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
2f60: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
2f70: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2f80: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2f90: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2fa0: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
2fb0: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
2fc0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
2fd0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
2fe0: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
2ff0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3000: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3010: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3020: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3030: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3060: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3070: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
3080: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
3090: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
30a0: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
30b0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
30c0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
30d0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
30e0: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
30f0: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3100: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3110: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3120: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3130: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3140: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3150: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3160: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3170: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
3180: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
3190: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
31a0: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
31b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
31c0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
31d0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
31e0: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
31f0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3200: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3210: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3220: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3230: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3240: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3250: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3260: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3270: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
3280: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
3290: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
32a0: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
32b0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
32c0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
32d0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
32e0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3300: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
3310: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3320: 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a  e_v2(sqlite3*);.
3330: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
3340: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
3350: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
3360: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
3370: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
3380: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
3390: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
33a0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
33b0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
33c0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
33d0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
33e0: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
33f0: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
3400: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3410: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
3420: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
3430: 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ace.**.** The sq
3440: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3450: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
3460: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20  enience wrapper 
3470: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
3480: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3490: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
34a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
34b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a  _finalize()],.**
34c0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20   that allows an 
34d0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72  application to r
34e0: 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74  un multiple stat
34f0: 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a  ements of SQL.**
3500: 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
3510: 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20  to use a lot of 
3520: 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e  C code. .**.** ^
3530: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
3540: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e  () interface run
3550: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55  s zero or more U
3560: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a  TF-8 encoded,.**
3570: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
3580: 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ate SQL statemen
3590: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69  ts passed into i
35a0: 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c  ts 2nd argument,
35b0: 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65  .** in the conte
35c0: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  xt of the [datab
35d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35e0: 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73  passed in as its
35f0: 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   1st.** argument
3600: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
3610: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  ack function of 
3620: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
3630: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3640: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3650: 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  L, then it is in
3660: 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72  voked for each r
3670: 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d  esult row.** com
3680: 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65  ing out of the e
3690: 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61  valuated SQL sta
36a0: 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34  tements.  ^The 4
36b0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  th argument to.*
36c0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
36d0: 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f   is relayed thro
36e0: 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61  ugh to the 1st a
36f0: 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a  rgument of each.
3700: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f  ** callback invo
3710: 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65  cation.  ^If the
3720: 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65   callback pointe
3730: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3740: 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20  c().** is NULL, 
3750: 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b  then no callback
3760: 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64   is ever invoked
3770: 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73   and result rows
3780: 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e   are.** ignored.
3790: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  .**.** ^If an er
37a0: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
37b0: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
37c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
37d0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71  assed into.** sq
37e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68  lite3_exec(), th
37f0: 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  en execution of 
3800: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
3810: 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a  ement stops and.
3820: 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74  ** subsequent st
3830: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69  atements are ski
3840: 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35  pped.  ^If the 5
3850: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3860: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3870: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  * is not NULL th
3880: 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73  en any error mes
3890: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20  sage is written 
38a0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
38b0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
38c0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
38d0: 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20  and passed back 
38e0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
38f0: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f  parameter..** To
3900: 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65   avoid memory le
3910: 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61  aks, the applica
3920: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f  tion should invo
3930: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
3940: 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20  ()].** on error 
3950: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
3960: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
3970: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3980: 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69  er of.** of sqli
3990: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
39a0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
39b0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
39c0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
39d0: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
39e0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
39f0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3a00: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3a10: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3a20: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3a30: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3a40: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3a50: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3a60: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3a70: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3a80: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3a90: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3aa0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3ab0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3ac0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3ad0: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3ae0: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3af0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3b00: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3b10: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3b20: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3b30: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3b40: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3b50: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3b60: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3b70: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3b80: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3b90: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3ba0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3bb0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3bc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3bd0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3be0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3bf0: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3c00: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3c10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3c20: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3c30: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3c40: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3c50: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3c60: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3c70: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3c80: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3c90: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3ca0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3cb0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3cc0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
3cd0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
3ce0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
3cf0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
3d00: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3d10: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3d20: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
3d30: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
3d40: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
3d50: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
3d60: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
3d70: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3d80: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
3d90: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
3da0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3db0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3dc0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
3dd0: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
3de0: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
3df0: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
3e00: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
3e10: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
3e20: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
3e30: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
3e40: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
3e50: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3e60: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
3e70: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
3e80: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
3e90: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
3ea0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
3eb0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69  plication must i
3ec0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3ef0: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
3f00: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
3f10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3f20: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f30: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f40: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
3f50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f60: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
3f70: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
3f80: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
3fa0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3fb0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
3fc0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
3fd0: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
3fe0: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
3ff0: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
4000: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4010: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4020: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4030: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4040: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4050: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4060: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
4070: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
4080: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
40b0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
40c0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
40d0: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
40f0: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4100: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4110: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4120: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4130: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4140: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4150: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
4180: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
4190: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
41a0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
41d0: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
41e0: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
41f0: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4200: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4210: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4220: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4230: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4240: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4250: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4260: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
4270: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4280: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4290: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
42a0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
42b0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
42c0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
42d0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
42e0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
42f0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4300: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4310: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4330: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4340: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4350: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4360: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
4370: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
4380: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
4390: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
43a0: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
43b0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
43d0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
43e0: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
43f0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4410: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4420: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4430: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4450: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4460: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4470: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
4480: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
44a0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
44b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
44c0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
44d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
44e0: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
44f0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4500: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4520: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4530: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4540: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4550: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4560: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4570: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
4580: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
4590: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
45a0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
45b0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
45c0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
45d0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
45e0: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
45f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4600: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4610: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4620: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4630: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4640: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4650: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4660: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4670: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
4680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4690: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
46a0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
46b0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
46c0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
46d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
46e0: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
46f0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4700: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4710: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4720: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4730: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4740: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4750: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4770: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
4780: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
4790: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
47a0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
47b0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
47c0: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
47d0: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
47e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
47f0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4800: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4810: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4830: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4840: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4850: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4860: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4870: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
4880: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
4890: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
48a0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
48b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48c0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
48d0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
48e0: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
48f0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4900: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4910: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4920: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4930: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4940: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4950: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4960: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4970: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4980: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4990: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
49a0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
49b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
49c0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
49d0: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
49e0: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
49f0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4a00: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
4a10: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
4a20: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4a30: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
4a40: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
4a50: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
4a60: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
4a70: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
4a80: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
4a90: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
4aa0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20  LITE_NOTICE     
4ab0: 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63   27   /* Notific
4ac0: 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69  ations from sqli
4ad0: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4ae0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
4af0: 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20  ING     28   /* 
4b00: 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71  Warnings from sq
4b10: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
4b30: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
4b40: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4b50: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
4b60: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
4b70: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
4b80: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
4b90: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4ba0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
4bb0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
4bc0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
4bd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4be0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
4bf0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4c00: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4c10: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4c20: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  ions}.**.** In i
4c30: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4c40: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4c50: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4c60: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69  turn one of 30 i
4c70: 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c  nteger.** [resul
4c80: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4c90: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4ca0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4cb0: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4cc0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4cd0: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4ce0: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4cf0: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4d00: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4d10: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4d20: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4d30: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4d40: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4d50: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4d60: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4d70: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4d80: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4d90: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4da0: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4db0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4dc0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4dd0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4de0: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4df0: 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74  rors. These [ext
4e00: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4e10: 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20  es] are enabled 
4e20: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
4e30: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
4e40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
4e50: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
4e60: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
4e70: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
4e80: 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65   API.  Or, the e
4e90: 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72  xtended code for
4ea0: 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63  .** the most rec
4eb0: 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65  ent error can be
4ec0: 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a   obtained using.
4ed0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4ee0: 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e  nded_errcode()].
4ef0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
4f10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
4f30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4f40: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
4f50: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
4f60: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
4f70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f80: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
4f90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fa0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
4fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fc0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
4fd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4fe0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
4ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5000: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5010: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5020: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
50b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
50d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5140: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5150: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5160: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
51c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
51d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5250: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5260: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5350: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5360: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5580: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5590: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
55a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
55b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
55c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
55d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
55e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5600: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5610: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5620: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5640: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5660: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5680: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5690: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
56a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
56d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
56e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
56f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5700: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5710: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5720: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5730: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5740: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5750: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5760: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5770: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5780: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5790: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
57a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
57b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
57c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
57d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
57e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
57f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5800: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5810: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5820: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5830: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5850: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5860: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5870: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5890: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
58a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
58b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
58c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
58e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
58f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5900: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5910: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5920: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5930: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5940: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5950: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5960: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5970: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5980: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5990: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
59a0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
59b0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
59c0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
59d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59e0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
59f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5a10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5a30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5a40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5a50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5a80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5aa0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5ab0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5ac0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ad0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5af0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5b00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5b20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5b40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5b60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5b80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5b90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ba0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5bc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5bd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5be0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5c00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5c10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5c20: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5c30: 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20  QLITE_AUTH_USER 
5c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5c50: 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c  QLITE_AUTH | (1<
5c60: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5c70: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5c80: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5c90: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5ca0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5cb0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5cc0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5cd0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5ce0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5cf0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5d00: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5d10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5d20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5d30: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5d50: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5d60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5d70: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5d80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5da0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5db0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5dc0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5dd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5df0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5e00: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5e10: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e20: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e40: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5e50: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5e60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5e70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e80: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5e90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5ea0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ec0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5ed0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5ee0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f00: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5f10: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5f20: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5f30: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f50: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
5f60: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
5f70: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5f80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fa0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
5fb0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
5fc0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fe0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
5ff0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
6000: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6020: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
6030: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
6040: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6060: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
6070: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
6080: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60a0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
60b0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
60c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60e0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
60f0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6100: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6120: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
6130: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6140: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6160: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
6170: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6180: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6190: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
61a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61b0: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
61c0: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
61d0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
61e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
61f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6200: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6210: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
6220: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6230: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6250: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
6260: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
6270: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6280: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62a0: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
62b0: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
62c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
62d0: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
62f0: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6300: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6310: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6320: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6330: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6340: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6350: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6360: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6370: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6380: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6390: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
63a0: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
63b0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
63c0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
63d0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
63e0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
63f0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6400: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6410: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6420: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6430: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6440: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6450: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6460: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6470: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6480: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6490: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
64a0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
64b0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
64c0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
64d0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
64e0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
64f0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6500: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6510: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6520: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6530: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6540: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6550: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6560: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6570: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6580: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6590: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
65a0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
65b0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
65c0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
65d0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
65e0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
65f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6600: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6610: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6620: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6630: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6640: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6650: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6660: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6670: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6680: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6690: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
66a0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
66b0: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
66c0: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
66d0: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
66e0: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
66f0: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6700: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6710: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6720: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6730: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6740: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6750: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6760: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6770: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6780: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6790: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
67a0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
67b0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
67c0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
67d0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
67e0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
67f0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6800: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6810: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6820: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6830: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6840: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6850: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6860: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6870: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6880: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6890: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
68a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
68b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68c0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
68d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
68e0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
68f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6900: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6910: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6920: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6930: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6940: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6950: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6960: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6980: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6990: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69a0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
69b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
69c0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
69d0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
69e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
69f0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6a00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a10: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a30: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6a40: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a60: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6a70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6a80: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6a90: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6aa0: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6ab0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6ac0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6ad0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6ae0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6af0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b00: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6b10: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6b20: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6b30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6b40: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6b50: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b70: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6b90: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
6ba0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6bb0: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6bc0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6bd0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6be0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6bf0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6c00: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6c10: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6c20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6c30: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6c40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6c50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6c60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6c70: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6c80: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6c90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6ca0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6cc0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6cd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6ce0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6cf0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6d00: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6d10: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6d20: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6d30: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6d40: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6d50: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6d60: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6d70: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6d80: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6d90: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6da0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6db0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6dc0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6dd0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6de0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6df0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6e00: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6e10: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6e20: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6e30: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6e40: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6e50: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6e60: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6e70: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6e80: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6e90: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6ea0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6eb0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6ec0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6ed0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6ee0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6ef0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6f00: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6f10: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6f20: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6f30: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6f40: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6f50: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6f60: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6f70: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6f80: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6f90: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6fa0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6fb0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6fc0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6fd0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6fe0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6ff0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
7000: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
7010: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
7020: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
7030: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
7040: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
7050: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
7060: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
7070: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
7080: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7090: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
70a0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
70b0: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
70c0: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
70d0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
70e0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
70f0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
7100: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
7110: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7120: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
7130: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
7140: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7150: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
7160: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
7170: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7180: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7190: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
71a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
71b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
71c0: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
71d0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
71e0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
71f0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
7200: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
7210: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7220: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
7230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7240: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7250: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
7260: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7270: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7280: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7290: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
72a0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
72b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
72c0: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
72d0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
72e0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
72f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
7300: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
7310: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7320: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
7330: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
7340: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7350: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
7360: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
7370: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7380: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7390: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
73a0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
73b0: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
73c0: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
73d0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
73e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
73f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7400: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
7410: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7420: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7430: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7440: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7450: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7460: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7470: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7480: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7490: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
74a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
74b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
74c0: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
74d0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
74e0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
74f0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7500: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
7510: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7520: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7530: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7540: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7550: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7560: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7570: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7580: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7590: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
75a0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
75b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
75c0: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
75d0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
75e0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
75f0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7600: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7610: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7620: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7630: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7640: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7650: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7660: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7670: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7680: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7690: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
76a0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
76b0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
76c0: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
76d0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
76e0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
76f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7700: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7710: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7720: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7730: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7740: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7750: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7760: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7770: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7780: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7790: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
77a0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
77b0: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
77c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
77d0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
77e0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
77f0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7800: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7810: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7820: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7830: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7840: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7850: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7860: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7870: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7880: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7890: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
78a0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
78b0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
78c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
78d0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
78e0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
78f0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7900: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7910: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7920: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7930: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7940: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7950: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7960: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7970: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7980: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7990: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
79a0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
79b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
79c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
79d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
79e0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
79f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7a00: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7a10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7a20: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7a30: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7a40: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7a50: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7a60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7a70: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7a80: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7a90: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7aa0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7ab0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7ac0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7ad0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7ae0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7af0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7b00: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7b10: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7b20: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7b30: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7b40: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7b50: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7b60: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7b70: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7b80: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7b90: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7ba0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7bb0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7bc0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7bd0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7be0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7bf0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7c00: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7c10: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7c20: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7c30: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7c40: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7c50: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7c60: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7c70: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7c80: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7c90: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7ca0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7cb0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7cc0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7cd0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7ce0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7cf0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7d00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7d10: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7d20: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7d30: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7d40: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7d50: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7d60: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7d70: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7d80: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7d90: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7da0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7db0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7dc0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7dd0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7de0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7df0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7e00: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7e10: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7e20: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
7e30: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
7e40: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
7e50: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
7e60: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
7e70: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
7e80: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
7e90: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
7ea0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
7eb0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
7ec0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
7ed0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
7ee0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7ef0: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
7f00: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
7f10: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
7f20: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
7f30: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
7f40: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
7f50: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
7f60: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
7f70: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
7f80: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
7f90: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
7fa0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7fb0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
7fc0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
7fd0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
7fe0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
7ff0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
8000: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
8010: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8020: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8030: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
8040: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
8050: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
8060: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
8070: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
8080: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8090: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
80a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
80b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
80c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
80d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
80e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
80f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8100: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
8110: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
8130: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8140: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
8150: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8160: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
8170: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8180: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8190: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
81a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
81b0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
81c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
81d0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
81e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
81f0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
8200: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8210: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8220: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8230: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8240: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8250: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8260: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8270: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8280: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8290: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
82a0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
82b0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
82c0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
82d0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
82e0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
82f0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8300: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8310: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8320: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8330: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8340: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8350: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
8360: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8370: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8380: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8390: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
83a0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
83b0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
83c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
83d0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
83e0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
83f0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8400: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8410: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8420: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8430: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8440: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8450: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8460: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8470: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8480: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8490: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
84a0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
84b0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
84c0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
84d0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
84e0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
84f0: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8500: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8510: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8520: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8530: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8540: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8550: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
8560: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8570: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8580: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
85a0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
85b0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
85c0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
85d0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
85e0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
85f0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8600: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8610: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8620: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8630: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8640: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8650: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8660: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8670: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8680: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8690: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
86a0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
86b0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
86c0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
86d0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
86e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
86f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8700: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8710: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8720: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8730: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8740: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8750: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8760: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8770: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8780: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8790: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
87c0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
87d0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
87e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
87f0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8800: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8810: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8820: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8830: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8840: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8850: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8860: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8870: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8880: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8890: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
88a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
88b0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
88c0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
88d0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
88e0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
88f0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8900: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8920: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8960: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8970: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8980: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8990: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
89a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
89b0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
89c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
89d0: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
89e0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
89f0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8a00: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8a10: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8a20: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8a30: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8a40: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8a60: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8a70: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8a80: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8a90: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8aa0: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8ab0: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8ac0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8ad0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8ae0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8af0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8b00: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8b10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8b20: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8b30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8b40: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8b50: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8b60: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8b70: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8b80: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8b90: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8ba0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8bb0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8bc0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8bd0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8be0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8bf0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8c00: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8c10: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8c20: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8c30: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8c50: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8c60: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8c70: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8c80: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8c90: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8ca0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8cb0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8cc0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8cd0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
8ce0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
8cf0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
8d00: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
8d10: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
8d20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8d30: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8d40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8d50: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8d60: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8d70: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8d80: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8d90: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8da0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8db0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8dc0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8dd0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8de0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8df0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
8e00: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
8e10: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8e20: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8e30: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8e40: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8e50: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8e60: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8e70: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8e80: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8e90: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8ea0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8eb0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8ed0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8ee0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8ef0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8f00: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
8f10: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8f20: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8f30: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8f40: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8f50: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8f60: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8f70: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8f80: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8f90: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8fa0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8fb0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
8fc0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8fd0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8fe0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8ff0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9000: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9010: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9020: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
9030: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
9040: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
9050: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
9060: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
9070: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
9080: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9090: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
90a0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
90b0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
90c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
90d0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
90e0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
90f0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9100: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9110: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9120: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9130: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9140: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9150: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
9160: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9170: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9180: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
9190: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
91a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
91b0: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
91c0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
91d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
91e0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
91f0: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9200: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9210: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9220: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9230: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9240: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9250: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9260: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9270: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9280: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9290: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
92a0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
92b0: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
92c0: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
92d0: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
92e0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
92f0: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9300: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9310: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9320: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9330: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9340: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9350: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9360: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9370: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9380: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9390: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
93a0: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
93b0: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
93c0: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
93d0: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
93e0: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
93f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9400: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9410: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9420: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9430: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9440: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9450: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9460: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
9470: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
9480: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
9490: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
94a0: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
94b0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
94c0: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
94d0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
94e0: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
94f0: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
9500: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
9510: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9520: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9530: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9540: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
9550: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
9560: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9570: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9580: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9590: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
95a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
95b0: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
95c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
95d0: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
95e0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
95f0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9600: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
9610: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
9620: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
9630: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
9640: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
9650: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
9660: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
9670: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
9680: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
9690: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
96a0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
96b0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
96c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
96d0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
96e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
96f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9700: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9710: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
9720: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
9730: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9740: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9750: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9760: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9780: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
9790: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
97a0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
97b0: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
97c0: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
97d0: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
97e0: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
97f0: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9800: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9810: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
9820: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
9830: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
9840: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
9850: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
9860: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
9870: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
9880: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
9890: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
98a0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
98b0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
98c0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
98d0: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
98e0: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
98f0: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9900: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9910: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
9920: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
9930: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
9940: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
9950: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
9960: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
9970: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
9980: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9990: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
99a0: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
99b0: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
99c0: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
99d0: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
99e0: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
99f0: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9a00: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9a10: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9a20: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
9a30: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
9a40: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
9a50: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
9a60: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
9a70: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
9a80: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
9a90: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
9aa0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
9ab0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
9ac0: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
9ad0: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
9ae0: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
9af0: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
9b00: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
9b10: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
9b20: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
9b30: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
9b40: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
9b50: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
9b60: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
9b70: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
9b80: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
9b90: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
9ba0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
9bb0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
9bc0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9bd0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
9be0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9bf0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9c00: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9c10: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9c20: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
9c30: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
9c40: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
9c50: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
9c60: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
9c70: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
9c80: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9c90: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
9ca0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
9cb0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
9cc0: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
9cd0: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
9ce0: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
9cf0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9d00: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
9d10: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
9d20: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
9d30: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
9d40: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
9d50: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
9d60: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
9d70: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
9d80: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
9d90: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
9da0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
9db0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
9dc0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
9dd0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
9de0: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
9df0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
9e00: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
9e10: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9e20: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
9e30: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
9e40: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
9e50: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
9e60: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9e70: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
9e80: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
9e90: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
9ea0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
9eb0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
9ec0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9ed0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9ee0: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
9ef0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
9f00: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
9f10: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
9f20: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
9f30: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
9f40: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
9f50: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
9f60: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
9f70: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
9f80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9f90: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9fa0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
9fc0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9fd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9fe0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9ff0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a000: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
a010: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
a020: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
a030: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
a040: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
a050: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
a060: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a070: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
a080: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
a090: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
a0a0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a0b0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a0c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a0d0: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a0e0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a0f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a100: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a110: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a120: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
a130: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
a140: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
a150: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
a160: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a170: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a180: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a190: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
a1a0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a1b0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a1c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a1d0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
a1e0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a1f0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
a200: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
a210: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
a220: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
a230: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
a240: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
a250: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
a260: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
a270: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
a280: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
a290: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
a2a0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
a2b0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
a2c0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
a2d0: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
a2e0: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
a2f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a300: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a310: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a320: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a330: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
a340: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
a350: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
a360: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
a370: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
a380: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
a390: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
a3a0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
a3b0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
a3c0: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
a3d0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
a3e0: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
a3f0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
a400: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
a410: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
a420: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
a430: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
a440: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
a450: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a460: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
a470: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
a480: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
a490: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
a4a0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
a4b0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
a4c0: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
a4d0: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
a4e0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
a4f0: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
a500: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
a510: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
a520: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
a530: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
a540: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
a550: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
a560: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
a570: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
a580: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
a590: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
a5a0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
a5b0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
a5c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a5d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
a5e0: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
a5f0: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
a600: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
a610: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a620: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
a630: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
a640: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
a650: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
a660: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
a670: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
a680: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
a690: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
a6a0: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
a6b0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
a6c0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a6d0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a6e0: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
a6f0: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
a700: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
a710: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
a720: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
a730: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
a740: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
a750: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
a760: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
a770: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a780: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
a790: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
a7a0: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
a7b0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
a7c0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
a7d0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a7e0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a7f0: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
a800: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
a810: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
a820: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
a830: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
a840: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
a850: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
a860: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
a870: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
a880: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
a890: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
a8a0: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
a8b0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
a8c0: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
a8d0: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
a8e0: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
a8f0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a910: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
a920: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
a930: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
a940: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
a950: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
a960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a970: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a980: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a990: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
a9a0: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
a9b0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
a9c0: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
a9d0: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
a9e0: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
a9f0: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
aa00: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
aa10: 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74  tatement.  ^If t
aa20: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aa30: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
aa40: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
aa50: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
aa60: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
aa70: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
aa80: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
aa90: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
aaa0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
aab0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
aac0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
aad0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
aae0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
aaf0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
ab00: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
ab10: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
ab20: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
ab30: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
ab40: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
ab50: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
ab60: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
ab70: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
ab80: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
ab90: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
aba0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
abb0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
abc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
abd0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
abe0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
abf0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
ac00: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
ac10: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
ac20: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
ac30: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
ac40: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
ac50: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
ac60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ac70: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
ac80: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
ac90: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
aca0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
acb0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
acc0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
acd0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
ace0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
acf0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
ad00: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
ad10: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
ad20: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
ad30: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
ad40: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
ad50: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
ad60: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
ad70: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
ad80: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
ad90: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
ada0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
adb0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
adc0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
add0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
ade0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
adf0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
ae00: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
ae10: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
ae20: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
ae30: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
ae40: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
ae50: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
ae60: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
ae70: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ae80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
ae90: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
aea0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
aeb0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
aec0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
aed0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
aee0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
aef0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
af00: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
af10: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
af20: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
af30: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
af40: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
af50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
af60: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
af70: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
af80: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
af90: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
afa0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
afb0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
afc0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
afd0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
afe0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
aff0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b000: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b010: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b020: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b030: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b040: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b050: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b060: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b070: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b080: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b0a0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b0b0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b0c0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b0d0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b0e0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b0f0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b100: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b110: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b120: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b130: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b140: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b150: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b160: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b170: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b180: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b190: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b1a0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b1b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b1c0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b1d0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b1e0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b1f0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b200: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b210: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b220: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b230: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b240: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b250: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b260: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b270: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b280: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b290: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b2a0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b2b0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b2c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b2d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b2e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b2f0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b300: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b310: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b320: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b330: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b340: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b350: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b360: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b370: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b380: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b390: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b3a0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b3b0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b3c0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b3d0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b3e0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b3f0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b400: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b410: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b420: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b430: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b440: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b450: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b460: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b470: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b480: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b490: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b4b0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b4c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b4d0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b4e0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
b4f0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
b500: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
b510: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
b520: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
b530: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
b540: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
b550: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
b560: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
b570: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
b580: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
b590: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b5a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b5b0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
b5c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b5d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b5e0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
b5f0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
b600: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
b610: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
b620: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
b630: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
b640: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
b650: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
b660: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
b670: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
b680: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
b690: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
b6a0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
b6b0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
b6c0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
b6d0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
b6e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ed..**.** </ul>.
b6f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b700: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
b710: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b720: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b730: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
b740: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
b750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b760: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
b770: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
b780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b790: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
b7a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
b7b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b7c0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
b7d0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
b7e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b7f0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
b800: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
b810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b820: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
b830: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
b840: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b850: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
b860: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
b870: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b880: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
b890: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
b8a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b8b0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
b8c0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
b8d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
b8e0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
b8f0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
b900: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b910: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
b920: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b940: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b950: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b960: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b970: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b980: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b990: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b9a0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b9b0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b9c0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b9d0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b9e0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b9f0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ba00: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
ba10: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
ba20: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
ba30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
ba40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ba50: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
ba60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
ba70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ba80: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
ba90: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
baa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bab0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
bac0: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
bad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bae0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
baf0: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 0a 2f 2a  DLE       23../*
bb00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
bb10: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
bb20: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
bb30: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
bb40: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
bb50: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
bb60: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
bb70: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
bb80: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
bb90: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
bba0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
bbb0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
bbc0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
bbd0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
bbe0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
bbf0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
bc00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
bc10: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
bc20: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
bc30: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
bc40: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
bc50: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
bc60: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
bc70: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
bc80: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
bc90: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
bca0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
bcb0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
bcc0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
bcd0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
bce0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
bcf0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
bd00: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
bd10: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
bd20: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
bd30: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
bd40: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
bd50: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
bd60: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
bd70: 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20  m".  See.** the 
bd80: 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d  [VFS | VFS docum
bd90: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75  entation] for fu
bda0: 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f  rther informatio
bdb0: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  n..**.** The val
bdc0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
bdd0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
bde0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
bdf0: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
be00: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
be10: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
be20: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
be30: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
be40: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
be50: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
be60: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
be70: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
be80: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
be90: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
bea0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
beb0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
bec0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
bed0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
bee0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
bef0: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
bf00: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
bf10: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
bf20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
bf30: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
bf40: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
bf50: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
bf60: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
bf70: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
bf80: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
bf90: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
bfa0: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
bfb0: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
bfc0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
bfd0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
bfe0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
bff0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
c000: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
c010: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
c020: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
c030: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
c040: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
c050: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
c060: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
c070: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
c080: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
c090: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
c0a0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
c0b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
c0c0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
c0d0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
c0e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
c0f0: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
c100: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c110: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
c120: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
c130: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
c140: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
c150: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
c160: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
c170: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
c180: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
c190: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
c1a0: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
c1b0: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
c1c0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
c1d0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
c1e0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
c1f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
c200: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
c210: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
c220: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
c230: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
c240: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
c250: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
c260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
c270: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
c280: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
c290: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
c2a0: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
c2b0: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
c2c0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
c2d0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
c2e0: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
c2f0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
c300: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
c310: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
c320: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
c330: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
c340: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
c350: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
c360: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
c370: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
c380: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
c390: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
c3a0: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
c3b0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c3c0: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
c3d0: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
c3e0: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
c3f0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
c400: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
c410: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
c420: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
c430: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
c440: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
c450: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
c460: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
c470: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
c480: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
c490: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
c4a0: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
c4b0: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
c4c0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
c4d0: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
c4e0: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
c4f0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
c500: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
c510: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
c520: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
c530: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
c540: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c550: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
c560: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
c570: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
c580: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
c590: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
c5a0: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
c5b0: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
c5c0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
c5d0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
c5e0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
c5f0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
c600: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
c610: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
c620: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
c630: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
c640: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
c650: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
c660: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
c670: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
c680: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c690: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
c6a0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
c6b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c6c0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
c6d0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
c6e0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
c6f0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
c700: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
c710: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
c720: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c730: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
c740: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
c750: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
c760: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
c770: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
c780: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c790: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
c7a0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
c7b0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
c7c0: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
c7d0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
c7e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c7f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c800: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
c810: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
c820: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
c830: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
c840: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c850: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
c860: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c870: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
c880: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c890: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
c8a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c8b0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
c8c0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c8d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
c8e0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
c8f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
c900: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
c910: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c920: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
c930: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c940: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
c950: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
c960: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
c970: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
c980: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
c990: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
c9a0: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
c9b0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
c9c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
c9d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
c9e0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
c9f0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
ca00: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
ca10: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
ca20: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
ca30: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
ca40: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
ca50: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
ca60: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
ca70: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
ca80: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
ca90: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
caa0: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
cab0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
cac0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
cad0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
cae0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
caf0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
cb00: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
cb10: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
cb20: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
cb30: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
cb40: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
cb50: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
cb60: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
cb70: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
cb80: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
cb90: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
cba0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
cbb0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
cbc0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
cbd0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cbe0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
cbf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc00: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
cc10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
cc20: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cc30: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
cc40: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
cc50: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
cc60: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
cc70: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
cc80: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
cc90: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
cca0: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
ccb0: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
ccc0: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
ccd0: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
cce0: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
ccf0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
cd00: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
cd10: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
cd20: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
cd30: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
cd40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
cd50: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
cd60: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
cd70: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
cd80: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
cd90: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
cda0: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
cdb0: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
cdc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
cdd0: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
cde0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
cdf0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
ce00: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
ce10: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
ce20: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
ce30: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
ce40: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
ce50: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
ce60: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
ce70: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
ce80: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
ce90: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
cea0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
ceb0: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
cec0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
ced0: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
cee0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
cef0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
cf00: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
cf10: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
cf20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
cf30: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
cf40: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
cf50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
cf60: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
cf70: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
cf80: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
cf90: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
cfa0: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
cfb0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
cfc0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
cfd0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
cfe0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
cff0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
d000: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
d010: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
d020: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
d030: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
d040: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
d050: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
d060: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
d070: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
d080: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
d090: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
d0a0: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
d0b0: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
d0c0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
d0d0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
d0e0: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
d0f0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
d100: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
d110: 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
d120: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
d130: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
d140: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
d150: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
d160: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
d170: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
d180: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
d190: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
d1a0: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
d1b0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d1c0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
d1d0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
d1e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d1f0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
d200: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
d210: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
d220: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
d230: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
d240: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
d250: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
d260: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
d270: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
d280: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
d290: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
d2a0: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
d2b0: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
d2c0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
d2d0: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
d2e0: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
d2f0: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
d300: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
d310: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
d320: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
d330: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
d340: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
d350: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
d360: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
d370: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
d380: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
d390: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
d3a0: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
d3b0: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
d3c0: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
d3d0: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
d3e0: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
d3f0: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
d400: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
d410: 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
d420: 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
d430: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
d440: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
d450: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
d460: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
d470: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
d480: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
d490: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
d4a0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
d4b0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
d4c0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
d4d0: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
d4e0: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
d4f0: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
d500: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
d510: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
d520: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
d530: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
d540: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
d550: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
d560: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
d570: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
d580: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
d590: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
d5a0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
d5b0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
d5c0: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
d5d0: 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
d5e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
d5f0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
d600: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
d610: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
d620: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
d630: 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
d640: 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
d650: 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
d660: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d670: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
d680: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
d690: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
d6a0: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20  mber multiplied 
d6b0: 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65  by 86400000 (the
d6c0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
d6d0: 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61  seconds in .** a
d6e0: 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20   24-hour day).  
d6f0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d700: 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e   use the xCurren
d710: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d720: 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63  hod to get the c
d730: 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61  urrent.** date a
d740: 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20  nd time if that 
d750: 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61  method is availa
d760: 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e  ble (if iVersion
d770: 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65   is 2 or .** gre
d780: 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e  ater and the fun
d790: 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
d7a0: 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77   not NULL) and w
d7b0: 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a  ill fall back.**
d7c0: 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65   to xCurrentTime
d7d0: 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69  () if xCurrentTi
d7e0: 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61  meInt64() is una
d7f0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  vailable..**.** 
d800: 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43  ^The xSetSystemC
d810: 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65  all(), xGetSyste
d820: 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65  mCall(), and xNe
d830: 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69  stSystemCall() i
d840: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
d850: 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65   not used by the
d860: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54   SQLite core.  T
d870: 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e  hese optional in
d880: 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
d890: 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65  vided.** by some
d8a0: 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69   VFSes to facili
d8b0: 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20  tate testing of 
d8c0: 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79  the VFS code. By
d8d0: 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20   overriding .** 
d8e0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74  system calls wit
d8f0: 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65  h functions unde
d900: 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61  r its control, a
d910: 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61   test program ca
d920: 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61  n.** simulate fa
d930: 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63  ults and error c
d940: 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77  onditions that w
d950: 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62  ould otherwise b
d960: 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f  e difficult.** o
d970: 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  r impossible to 
d980: 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74  induce.  The set
d990: 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73   of system calls
d9a0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
d9b0: 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65  rridden.** varie
d9c0: 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74  s from one VFS t
d9d0: 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66  o another, and f
d9e0: 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20  rom one version 
d9f0: 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  of the same VFS 
da00: 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
da10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
da20: 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74  at use these int
da30: 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20  erfaces must be 
da40: 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79  prepared for any
da50: 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68  .** or all of th
da60: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ese interfaces t
da70: 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72  o be NULL or for
da80: 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20   their behavior 
da90: 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f  to change.** fro
daa0: 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
dab0: 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c   the next.  Appl
dac0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f  ications must no
dad0: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63  t attempt to acc
dae0: 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68  ess.** any of th
daf0: 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74  ese methods if t
db00: 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74  he iVersion of t
db10: 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74  he VFS is less t
db20: 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65  han 3..*/.typede
db30: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
db40: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
db50: 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  ;.typedef void (
db60: 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
db70: 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
db80: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
db90: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
dba0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
dbb0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
dbc0: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
dbd0: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
dbe0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
dbf0: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
dc00: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
dc10: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
dc20: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
dc30: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
dc40: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
dc50: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
dc60: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
dc70: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
dc80: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
dc90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dca0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
dcb0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
dcc0: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
dcd0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
dce0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
dcf0: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
dd00: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
dd10: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
dd20: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
dd30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
dd40: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
dd50: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
dd60: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
dd70: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
dd80: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
dd90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dda0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ddb0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
ddc0: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
ddd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dde0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ddf0: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
de00: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
de10: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
de20: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
de30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
de40: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
de50: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
de60: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
de70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
de80: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
de90: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
dea0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
deb0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
dec0: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
ded0: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
dee0: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
def0: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
df00: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
df10: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
df20: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
df30: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
df40: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
df50: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
df60: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
df70: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
df80: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
df90: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
dfa0: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
dfb0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
dfc0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
dfd0: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
dfe0: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
dff0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
e000: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
e010: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e020: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e030: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
e040: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
e050: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
e060: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
e070: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
e080: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
e090: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
e0a0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
e0b0: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
e0c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
e0d0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e0e0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e0f0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
e100: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
e110: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
e120: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
e130: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
e140: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
e150: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
e160: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
e170: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e180: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e190: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e1a0: 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
e1b0: 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65  yscall_ptr (*xGe
e1c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e1d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e1e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
e1f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78   const char *(*x
e200: 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
e210: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e220: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e230: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
e240: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
e250: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
e260: 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
e270: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e280: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
e290: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
e2a0: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
e2b0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
e2c0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
e2d0: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
e2e0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
e2f0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
e300: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e310: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
e320: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
e330: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e340: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e350: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
e360: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
e370: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
e380: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
e390: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
e3a0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
e3b0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
e3c0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
e3d0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
e3e0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
e3f0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
e400: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e410: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
e420: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
e430: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
e440: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
e450: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
e460: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
e470: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
e480: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
e490: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
e4a0: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
e4b0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
e4c0: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
e4d0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
e4e0: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
e4f0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
e500: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
e510: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
e520: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
e530: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e540: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
e550: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
e560: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
e570: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
e580: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
e590: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
e5a0: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
e5b0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
e5c0: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
e5d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e5e0: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
e5f0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
e600: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
e610: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
e620: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e630: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
e640: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
e650: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
e660: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
e670: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
e680: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
e690: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e6a0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e6b0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
e6c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e6d0: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
e6e0: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
e6f0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
e700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e710: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
e720: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
e730: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
e740: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e750: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
e760: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
e770: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
e780: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
e790: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
e7a0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
e7b0: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
e7c0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
e7d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e7e0: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
e7f0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
e800: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
e810: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
e820: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
e830: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
e840: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e850: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e860: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e870: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e880: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e890: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e8a0: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
e8b0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e8c0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
e8d0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
e8e0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
e8f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e900: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
e910: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
e920: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
e930: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
e940: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
e950: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
e960: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
e970: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
e980: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
e990: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
e9a0: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
e9b0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
e9c0: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
e9d0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
e9e0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
e9f0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
ea00: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
ea10: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
ea20: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
ea30: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
ea40: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
ea50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
ea60: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
ea70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ea80: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
ea90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
eaa0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
eab0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
eac0: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
ead0: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
eae0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
eaf0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
eb00: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
eb10: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
eb20: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
eb30: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
eb40: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
eb50: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
eb60: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
eb70: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
eb80: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
eb90: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
eba0: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
ebb0: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
ebc0: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
ebd0: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
ebe0: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
ebf0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
ec00: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
ec10: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
ec20: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
ec30: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
ec40: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
ec50: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
ec60: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
ec70: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
ec80: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
ec90: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
eca0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
ecb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
ecc0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
ecd0: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
ece0: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
ecf0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
ed00: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
ed10: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
ed20: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
ed30: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
ed40: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
ed50: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
ed60: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
ed70: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
ed80: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
ed90: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
eda0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
edb0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
edc0: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
edd0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
ede0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
edf0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
ee00: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
ee10: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
ee20: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
ee30: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
ee40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ee50: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
ee60: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
ee70: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ee80: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
ee90: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
eea0: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
eeb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
eec0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
eed0: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
eee0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
eef0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
ef00: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
ef10: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ef20: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
ef30: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
ef40: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
ef50: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
ef60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
ef70: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
ef80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ef90: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
efa0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
efb0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
efc0: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
efd0: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
efe0: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
eff0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
f000: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f010: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f020: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
f030: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f040: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
f050: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
f060: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
f070: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
f080: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
f090: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
f0a0: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
f0b0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
f0c0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
f0d0: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
f0e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
f0f0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
f100: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
f110: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
f120: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
f130: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
f140: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
f150: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
f160: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
f170: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
f180: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
f190: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
f1a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
f1b0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
f1c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f1d0: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
f1e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f1f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
f200: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f210: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
f220: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
f230: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
f240: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
f250: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
f260: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
f270: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
f280: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
f290: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
f2a0: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
f2b0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
f2c0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
f2d0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
f2e0: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
f2f0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
f300: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
f310: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f320: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
f330: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
f340: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
f350: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
f360: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
f370: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
f380: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
f390: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
f3a0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
f3b0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
f3c0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
f3d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f3e0: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
f3f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
f400: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
f410: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
f420: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
f430: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
f440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
f450: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
f460: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
f470: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
f480: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
f490: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f4a0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
f4b0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
f4c0: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
f4d0: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
f4e0: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
f4f0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f500: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f510: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
f520: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
f530: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
f540: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
f550: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
f560: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
f570: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f580: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
f590: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
f5a0: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
f5b0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
f5c0: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
f5d0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
f5e0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
f5f0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
f600: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
f610: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
f620: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
f630: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
f640: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
f650: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
f660: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
f670: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
f680: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f690: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
f6a0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
f6b0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
f6c0: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
f6d0: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
f6e0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
f6f0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
f700: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f710: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
f720: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
f730: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
f740: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
f750: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f760: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
f770: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
f780: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
f790: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
f7a0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
f7b0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
f7c0: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
f7d0: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
f7e0: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
f7f0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
f800: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
f810: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
f820: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
f830: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
f840: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
f850: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
f860: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
f870: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
f880: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
f890: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
f8a0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
f8b0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f8c0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
f8d0: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
f8e0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f8f0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f900: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
f910: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
f920: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
f930: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
f940: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
f950: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f960: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
f970: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
f980: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
f990: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
f9a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f9b0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
f9c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
f9d0: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
f9e0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f9f0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
fa00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
fa10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
fa20: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
fa30: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
fa40: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
fa50: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
fa60: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
fa70: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
fa80: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
fa90: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
faa0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
fab0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
fac0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
fad0: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
fae0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
faf0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fb00: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
fb10: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
fb20: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
fb30: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fb40: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
fb50: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
fb60: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
fb70: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
fb80: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
fb90: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
fba0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
fbb0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
fbc0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
fbd0: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
fbe0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
fbf0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
fc00: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
fc10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fc20: 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  e(void);.SQLITE_
fc30: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
fc40: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
fc50: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
fc60: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
fc70: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
fc80: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
fc90: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
fca0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
fcb0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
fcc0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fcd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fce0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fcf0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
fd00: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
fd10: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
fd20: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
fd30: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
fd40: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
fd50: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
fd60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
fd70: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
fd80: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
fd90: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
fda0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
fdb0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
fdc0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
fdd0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
fde0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
fdf0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
fe00: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
fe10: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
fe20: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
fe30: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fe40: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
fe50: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
fe60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
fe70: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
fe80: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
fe90: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
fea0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
feb0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
fec0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
fed0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
fee0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
fef0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
ff00: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
ff10: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
ff20: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
ff30: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
ff40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ff50: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
ff60: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
ff70: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
ff80: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
ff90: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
ffa0: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
ffb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
ffc0: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
ffd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ffe0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
fff0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
10000 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
10010 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
10020 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
10030 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
10040 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
10050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10060 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
10070 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
10080 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
10090 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
100a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
100b0 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
100c0 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
100d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
100e0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
100f0 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
10100 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
10110 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
10120 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
10130 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
10140 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
10150 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
10160 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
10170 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
10180 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
10190 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
101a0 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
101b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
101c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
101d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
101e0 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
101f0 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
10200 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
10210 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
10220 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
10230 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
10240 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51  ror code]..*/.SQ
10250 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
10260 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
10270 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10280 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10290 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
102a0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
102b0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
102c0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
102d0 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
102e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
102f0 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
10300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10310 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
10320 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
10330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10340 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
10350 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
10360 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
10370 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10380 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
10390 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
103a0 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
103b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
103c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
103d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
103e0 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
103f0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
10400 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
10410 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
10420 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
10430 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
10440 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
10450 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
10460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
10470 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
10480 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
10490 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
104a0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
104b0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
104c0 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
104d0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
104e0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
104f0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
10500 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
10510 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
10520 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
10530 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
10540 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
10550 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
10560 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
10570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
10580 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
10590 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
105a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
105b0 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
105c0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
105d0 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
105e0 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
105f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10600 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
10610 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
10620 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
10630 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
10640 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
10650 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
10660 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
10670 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
10680 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
10690 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
106a0 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
106b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
106c0 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
106d0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
106e0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
106f0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
10700 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
10710 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
10720 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
10730 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
10740 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
10750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10760 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
10770 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
10780 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
10790 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
107a0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
107b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
107c0 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
107d0 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
107e0 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
107f0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
10800 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
10810 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
10820 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
10830 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
10840 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
10850 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
10860 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
10870 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
10880 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
10890 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
108a0 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
108b0 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
108c0 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
108d0 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
108e0 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
108f0 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
10900 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
10910 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
10920 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
10930 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
10940 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
10950 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
10960 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10970 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10980 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
10990 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
109a0 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
109b0 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
109c0 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
109d0 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
109e0 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
109f0 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
10a00 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
10a10 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
10a20 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
10a30 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
10a40 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
10a50 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
10a60 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
10a70 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
10a80 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
10a90 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
10aa0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
10ab0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10ac0 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
10ad0 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
10ae0 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
10af0 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
10b00 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
10b10 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
10b20 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
10b30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10b40 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
10b50 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
10b60 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
10b70 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
10b80 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
10b90 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
10ba0 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
10bb0 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
10bc0 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
10bd0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
10be0 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
10bf0 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
10c00 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
10c10 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
10c20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
10c30 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
10c40 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
10c50 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
10c60 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
10c70 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
10c80 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
10c90 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
10ca0 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
10cb0 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
10cc0 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
10cd0 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
10ce0 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
10cf0 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
10d00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
10d10 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
10d20 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
10d30 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
10d40 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10d50 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
10d60 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
10d70 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
10d80 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
10d90 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
10da0 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
10db0 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
10dc0 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
10dd0 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
10de0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
10df0 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  cator.  For exam
10e00 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
10e10 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
10e20 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
10e30 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
10e40 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
10e50 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
10e60 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10e70 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
10e80 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
10e90 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10ea0 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
10eb0 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
10ec0 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
10ed0 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
10ee0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
10ef0 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
10f00 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
10f10 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
10f20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
10f30 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
10f40 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
10f50 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
10f60 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
10f70 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
10f80 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
10f90 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
10fa0 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
10fb0 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
10fc0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10fd0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
10fe0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
10ff0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
11000 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
11010 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
11020 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
11030 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
11040 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
11050 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11060 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
11070 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
11080 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
11090 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
110a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
110b0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
110c0 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
110d0 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
110e0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
110f0 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
11100 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
11110 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
11120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11130 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
11140 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
11150 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
11160 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
11170 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
11180 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
11190 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
111a0 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
111b0 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
111c0 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
111d0 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
111e0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
111f0 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
11200 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
11210 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
11220 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
11230 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
11240 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
11250 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
11260 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
11270 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
11280 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
11290 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
112a0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
112b0 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
112c0 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
112d0 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
112e0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
112f0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
11300 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
11310 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
11320 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
11330 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
11340 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
11350 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
11360 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11370 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
11380 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
11390 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
113a0 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
113b0 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
113c0 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
113d0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
113e0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
113f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11400 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
11410 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
11420 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
11430 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
11440 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
11450 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
11460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
11470 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
11480 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
11490 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
114a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
114b0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
114c0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
114d0 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
114e0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
114f0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
11500 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
11510 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
11520 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
11530 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
11540 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
11550 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
11560 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11570 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
11580 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
11590 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
115a0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
115b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
115c0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
115d0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
115e0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
115f0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
11600 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
11610 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
11620 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
11630 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
11640 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
11650 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
11660 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
11670 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
11680 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
11690 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
116a0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
116b0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
116c0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
116d0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
116e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
116f0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
11700 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
11710 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11720 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
11730 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11740 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
11750 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11760 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11770 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11780 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11790 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
117a0 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
117b0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
117c0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
117d0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
117e0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
117f0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
11800 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
11810 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
11820 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
11830 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
11840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
118a0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
118b0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
118c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
118d0 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
118e0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
118f0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
11900 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11910 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11920 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
11930 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11940 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
11950 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11960 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
11970 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11980 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11990 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
119a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
119b0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
119c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
119d0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
119e0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
119f0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11a00 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11a10 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11a20 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
11a30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11a40 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
11a50 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
11a60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11a70 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11a80 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11a90 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
11aa0 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
11ab0 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
11ac0 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
11ad0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11ae0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11af0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11b00 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
11b10 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
11b20 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
11b30 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
11b40 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
11b50 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
11b60 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
11b70 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
11b80 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
11b90 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
11ba0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11bb0 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
11bc0 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
11bd0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11be0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11bf0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11c00 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11c10 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11c20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11c30 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11c40 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
11c50 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
11c60 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11c70 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
11c80 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11c90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11ca0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11cb0 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11cc0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11cd0 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
11ce0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11cf0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11d00 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11d10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11d20 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
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 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
11da0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
11db0 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
11dc0 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
11dd0 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
11de0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
11df0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
11e00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
11e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11e20 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
11e30 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
11e40 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
11e50 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
11e60 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11e70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
11e80 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
11e90 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
11ea0 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
11eb0 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
11ec0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ed0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
11ee0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
11ef0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
11f00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
11f10 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
11f20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
11f30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
11f40 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
11f50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
11f60 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
11f70 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
11f80 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
11f90 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11fa0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11fb0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11fc0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11fd0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11fe0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11ff0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12000 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12010 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
12020 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
12030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12040 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12050 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12060 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12070 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12080 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
12090 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
120a0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
120b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
120c0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
120d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
120e0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
120f0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12100 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12110 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12120 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12130 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12140 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12150 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12160 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
12170 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
12180 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
12190 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
121a0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
121b0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
121c0 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
121d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
121e0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
121f0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
12200 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
12210 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
12220 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
12230 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
12240 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12250 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
12260 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
12270 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
12280 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
12290 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
122a0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
122b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
122c0 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
122d0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
122e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
122f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12300 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12310 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12320 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12330 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12340 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
12350 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12360 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
12370 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
12380 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
12390 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
123a0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
123b0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
123c0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
123d0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
123e0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
123f0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
12400 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
12410 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
12420 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
12430 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
12440 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
12450 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
12460 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
12470 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12480 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
12490 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
124a0 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
124b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
124c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
124d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
124e0 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
124f0 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
12500 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
12510 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
12520 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
12530 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
12540 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
12550 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
12560 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12570 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
12580 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
12590 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
125a0 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
125b0 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
125c0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
125d0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
125e0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
125f0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12600 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
12610 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
12620 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
12630 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
12640 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12650 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
12660 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
12670 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12680 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
12690 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
126a0 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
126b0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
126c0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
126d0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
126e0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
126f0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
12700 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12710 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
12720 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
12730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12740 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
12750 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12760 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
12770 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12780 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12790 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
127a0 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
127b0 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
127c0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
127d0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
127e0 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
127f0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
12800 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
12810 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
12820 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
12830 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
12840 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
12850 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
12860 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12870 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
12880 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
12890 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
128a0 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
128b0 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
128c0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
128d0 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
128e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
128f0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
12900 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
12910 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
12920 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
12930 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
12940 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
12950 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
12960 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
12970 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
12980 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
12990 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
129a0 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
129b0 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
129c0 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
129d0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
129e0 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
129f0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
12a00 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
12a10 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
12a20 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
12a30 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
12a40 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
12a50 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
12a60 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
12a70 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
12a80 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
12a90 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
12aa0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
12ab0 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
12ac0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
12ad0 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
12ae0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
12af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12b00 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
12b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12b20 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
12b30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12b40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12b50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12b60 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12b70 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
12b80 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
12b90 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
12ba0 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
12bb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
12bc0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
12bd0 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
12be0 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
12bf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12c00 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
12c10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12c20 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
12c30 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
12c40 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
12c50 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
12c60 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
12c70 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
12c80 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
12c90 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
12ca0 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
12cb0 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
12cc0 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
12cd0 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
12ce0 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
12cf0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
12d00 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
12d10 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
12d20 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
12d30 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
12d40 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
12d50 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
12d60 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
12d70 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
12d80 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
12d90 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
12da0 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
12db0 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
12dc0 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
12dd0 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
12de0 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
12df0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
12e00 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
12e10 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
12e20 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
12e30 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
12e40 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
12e50 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
12e60 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
12e70 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
12e80 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
12e90 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
12ea0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
12eb0 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
12ec0 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
12ed0 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
12ee0 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
12ef0 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
12f00 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
12f10 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
12f20 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
12f30 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
12f40 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
12f50 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
12f60 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
12f70 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
12f80 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
12f90 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
12fa0 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
12fb0 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
12fc0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
12fd0 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
12fe0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
12ff0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
13000 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
13010 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
13020 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
13030 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13040 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
13050 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13060 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
13070 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
13080 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13090 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
130a0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
130b0 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
130c0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
130d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
130e0 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
130f0 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
13100 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
13110 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
13120 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
13130 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
13140 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
13150 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
13160 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
13170 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
13180 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
13190 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
131a0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
131b0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
131c0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
131d0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
131e0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
131f0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13200 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
13210 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
13220 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
13230 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
13240 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
13250 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
13260 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
13270 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
13280 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
13290 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
132a0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
132b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
132c0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
132d0 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
132e0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
132f0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
13300 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
13310 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
13320 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
13330 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13340 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
13350 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
13360 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
13370 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
13380 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
13390 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
133a0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
133b0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
133c0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
133d0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
133e0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
133f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
13400 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
13410 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
13420 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
13430 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
13440 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
13450 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
13460 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13470 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
13480 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
13490 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
134a0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
134b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
134c0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
134d0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
134e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
134f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13500 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
13510 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13520 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13530 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13540 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
13550 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
13560 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
13570 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
13580 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
13590 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
135a0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
135b0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
135c0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
135d0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
135e0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
135f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
13600 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13610 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
13620 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
13630 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
13640 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
13650 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
13660 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
13670 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
13680 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13690 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
136a0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
136b0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
136c0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
136d0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
136e0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
136f0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
13700 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13710 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
13720 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
13730 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13740 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
13750 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13760 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13770 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13780 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
13790 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
137a0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
137b0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
137c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
137d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
137e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
137f0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13800 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13810 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13820 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
13830 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13840 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13850 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13860 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13870 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
13880 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
13890 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
138a0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
138b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
138c0 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
138d0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
138e0 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
138f0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
13900 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
13910 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
13920 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
13930 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
13940 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13950 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13960 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13970 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13980 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13990 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
139a0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
139b0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
139c0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
139d0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
139e0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
139f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13a00 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
13a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13a20 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
13a30 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
13a40 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
13a50 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
13a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13a70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
13a80 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13a90 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
13aa0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13ab0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
13ac0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
13ad0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
13ae0 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
13af0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
13b00 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
13b10 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
13b20 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
13b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
13b40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13b50 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
13b60 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
13b70 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
13b80 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
13b90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
13ba0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
13bb0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
13bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
13bd0 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
13be0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
13bf0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
13c00 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
13c10 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
13c20 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
13c30 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
13c40 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
13c50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
13c60 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
13c70 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
13c80 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
13c90 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
13ca0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13cb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13cc0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
13cd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
13ce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13cf0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13d00 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13d10 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13d20 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
13d30 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
13d40 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
13d50 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
13d60 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
13d70 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
13d80 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
13d90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
13da0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13db0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
13dc0 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
13dd0 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
13de0 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
13df0 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
13e00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13e10 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
13e20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e30 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
13e40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
13e50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13e60 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13e70 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
13e80 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
13e90 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13ea0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
13eb0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
13ec0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
13ed0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
13ee0 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
13ef0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
13f00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13f10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
13f20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f30 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
13f40 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
13f50 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
13f60 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
13f70 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
13f80 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
13f90 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
13fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13fb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13fc0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
13fd0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
13fe0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
13ff0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
14000 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
14010 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
14020 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
14030 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
14040 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
14050 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
14060 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
14070 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
14080 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
14090 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
140a0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
140b0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
140c0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
140d0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
140e0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
140f0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
14100 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
14110 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
14120 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
14130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14140 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
14150 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
14160 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
14170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14180 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14190 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
141a0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
141b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
141c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
141d0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
141e0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
141f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
14200 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14210 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
14220 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
14230 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
14240 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
14250 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
14260 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
14270 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
14280 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
14290 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
142a0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
142b0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
142c0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
142d0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
142e0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
142f0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
14300 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
14310 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
14320 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
14330 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
14340 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
14350 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
14360 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
14370 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
14380 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
14390 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
143a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
143b0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
143c0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
143d0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
143e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
143f0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
14400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14410 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 6f  .** <dd>^(This o
14420 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14430 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14440 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
14450 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
14460 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14470 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
14480 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
14490 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
144a0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
144b0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
144c0 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
144d0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
144e0 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
144f0 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
14500 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
14510 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
14520 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
14530 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
14540 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
14550 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
14560 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
14570 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
14580 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
14590 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
145a0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
145b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
145c0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
145d0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
145e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
145f0 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73  pened. ^If it is
14600 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
14610 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
14620 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
14630 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
14640 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
14650 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
14660 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
14670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14680 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79   is opened. ^(By
14690 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
146a0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
146b0 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
146c0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
146d0 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
146e0 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
146f0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
14700 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
14710 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a  l defined.)^.**.
14720 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14730 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14740 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
14750 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14760 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
14770 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69  * <dd>^This opti
14780 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14790 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65  e integer argume
147a0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
147b0 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20  rpreted as.** a 
147c0 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
147d0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
147e0 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
147f0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
14800 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61  s for.** full ta
14810 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
14820 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
14830 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
14840 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
14850 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
14860 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
14870 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14880 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
14890 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
148a0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
148b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
148c0 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
148d0 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
148e0 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
148f0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14900 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
14910 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
14920 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
14930 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
14940 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
14950 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
14960 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
14970 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
14980 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
14990 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
149a0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
149b0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
149c0 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
149d0 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
149e0 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
149f0 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
14a00 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
14a10 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
14a20 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
14a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14a40 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
14a50 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
14a60 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14a70 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
14a80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14a90 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
14aa0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
14ab0 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
14ac0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
14ad0 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
14ae0 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
14af0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
14b00 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
14b10 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
14b20 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
14b30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14b40 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
14b50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14b60 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
14b70 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
14b80 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
14b90 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
14ba0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14bb0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
14bc0 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
14bd0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
14be0 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
14bf0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
14c00 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
14c10 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
14c20 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
14c30 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
14c40 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
14c50 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
14c60 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
14c70 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
14c80 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
14c90 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
14ca0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
14cb0 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
14cc0 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
14cd0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
14ce0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
14cf0 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
14d00 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
14d10 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
14d20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
14d30 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
14d40 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
14d50 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
14d60 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
14d70 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14d80 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
14d90 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
14da0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
14db0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
14dc0 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
14dd0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14de0 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
14df0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
14e00 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
14e10 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
14e20 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
14e30 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
14e40 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
14e50 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
14e60 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
14e70 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
14e80 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14e90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
14ea0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
14eb0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
14ec0 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
14ed0 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
14ee0 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
14ef0 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
14f00 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14f10 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
14f20 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
14f30 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
14f40 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
14f50 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
14f60 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
14f70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14f80 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
14f90 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14fa0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
14fb0 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
14fc0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
14fd0 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
14fe0 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
14ff0 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
15000 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
15010 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
15020 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
15030 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
15040 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
15050 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
15060 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15070 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
15080 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
15090 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
150a0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
150b0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
150c0 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
150d0 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
150e0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
150f0 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
15100 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
15110 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
15120 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
15130 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
15140 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15150 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  .** cannot be ch
15160 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  anged at run-tim
15170 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20  e.  Nor may the 
15180 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
15190 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63  mmap size.** exc
151a0 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  eed the compile-
151b0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
151c0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
151d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
151e0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
151f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
15200 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
15210 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
15220 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
15230 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
15240 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
15250 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
15260 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
15270 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
15280 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15290 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
152a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
152b0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
152c0 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69  * <dd>^This opti
152d0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
152e0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
152f0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  s compiled for W
15300 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20 74  indows.** with t
15310 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
15320 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
15330 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15340 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45 5f  ined..** SQLITE_
15350 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15360 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
15370 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
15380 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
15390 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
153a0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
153b0 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
153c0 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ap..** </dl>.*/.
153d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
153e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
153f0 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
15400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15410 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
15420 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
15430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15440 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
15450 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
15460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15470 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
15480 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
15490 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
154a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
154b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
154c0 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
154d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
154e0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15500 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
15510 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
15520 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
15530 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15540 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
15550 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
15560 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
15570 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15580 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
15590 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
155a0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
155b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
155c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
155d0 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
155e0 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
155f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15600 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
15610 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
15620 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
15630 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15640 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
15650 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
15660 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
15670 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
15680 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
15690 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
156a0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
156b0 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
156c0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
156d0 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
156e0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
156f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15700 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
15710 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
15720 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15730 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
15740 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
15750 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15760 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
15770 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
15780 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
15790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
157a0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
157b0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
157c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
157d0 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
157e0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
157f0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
15800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15810 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
15820 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
15830 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
15840 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15850 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15860 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
15870 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
15880 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15890 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
158a0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
158b0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
158c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
158d0 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
158e0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
158f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
15900 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15910 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15920 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
15930 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
15940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15950 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
15960 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
15970 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
15980 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
15990 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
159a0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
159b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
159c0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
159d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
159e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
159f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
15a00 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
15a10 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
15a20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15a30 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
15a40 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
15a50 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
15a60 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
15a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15a80 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
15a90 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
15aa0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
15ab0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
15ac0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
15ad0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15ae0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
15af0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
15b00 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
15b10 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15b20 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
15b30 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
15b40 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
15b50 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
15b60 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
15b70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
15b80 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
15b90 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
15ba0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
15bb0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15bc0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
15bd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
15be0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
15bf0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
15c00 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
15c10 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
15c20 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
15c30 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
15c40 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
15c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15c60 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
15c70 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
15c80 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
15c90 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
15ca0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
15cb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
15cc0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
15cd0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
15ce0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
15cf0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
15d00 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
15d10 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
15d20 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
15d30 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
15d40 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
15d50 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
15d60 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15d70 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
15d80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15d90 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
15da0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
15db0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
15dc0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
15dd0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
15de0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
15df0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
15e00 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
15e10 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
15e20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
15e30 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
15e40 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
15e50 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
15e60 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
15e70 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
15e80 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
15e90 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
15ea0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
15eb0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
15ec0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
15ed0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
15ee0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15ef0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
15f00 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
15f10 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
15f20 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
15f30 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
15f40 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
15f50 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
15f60 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
15f70 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
15f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15f90 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
15fa0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
15fb0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
15fc0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
15fd0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
15fe0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
15ff0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
16000 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
16010 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
16020 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
16030 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
16040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16050 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
16060 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
16070 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
16080 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
16090 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
160a0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
160b0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
160c0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
160d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
160e0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
160f0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
16100 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
16110 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16120 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
16130 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
16140 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
16150 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
16160 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
16170 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
16180 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
16190 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
161a0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
161b0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
161c0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
161d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
161e0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
161f0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
16200 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
16210 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
16220 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
16230 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
16240 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
16250 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
16260 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
16270 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
16280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16290 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
162a0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
162b0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
162c0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
162d0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
162e0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
162f0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16300 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16310 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16320 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16330 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
16340 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16350 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
16360 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
16370 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
16380 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16390 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
163a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
163b0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
163c0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
163d0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
163e0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
163f0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
16400 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
16410 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
16420 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
16430 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
16440 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
16450 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
16460 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
16470 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
16480 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
16490 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
164a0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
164b0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
164c0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
164d0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
164e0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
164f0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
16500 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
16510 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
16520 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
16530 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
16540 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
16550 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16560 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
16570 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
16580 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
16590 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
165a0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
165b0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
165c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
165d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
165e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
165f0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
16600 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
16610 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16620 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
16630 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
16640 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
16650 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16660 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
16670 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
16680 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
16690 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
166a0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
166b0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
166c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
166d0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
166e0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
166f0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
16700 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
16710 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16720 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
16730 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
16740 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
16750 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
16760 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
16770 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
16780 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
16790 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
167a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
167b0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
167c0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
167d0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
167e0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
167f0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
16800 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
16810 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
16820 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
16830 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
16840 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
16850 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
16860 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
16870 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
16880 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
16890 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
168a0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
168b0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
168c0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
168d0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
168e0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
168f0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
16900 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
16910 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
16920 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
16930 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
16940 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
16950 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
16960 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
16970 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
16980 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
16990 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
169a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
169b0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
169c0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
169d0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
169e0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
169f0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
16a00 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
16a10 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
16a20 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
16a30 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
16a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16a50 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
16a60 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
16a70 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
16a80 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
16a90 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
16aa0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
16ab0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
16ac0 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
16ad0 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
16ae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16af0 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
16b00 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16b10 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
16b20 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
16b30 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
16b40 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
16b50 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
16b60 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
16b70 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
16b80 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
16b90 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
16ba0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
16bb0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
16bc0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
16bd0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
16be0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
16bf0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
16c00 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
16c10 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
16c20 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
16c30 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16c40 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
16c50 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
16c60 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
16c70 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
16c80 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
16c90 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
16ca0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
16cb0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
16cc0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
16cd0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
16ce0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
16cf0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16d00 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
16d10 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
16d20 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
16d30 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
16d40 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
16d50 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
16d60 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
16d70 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
16d80 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
16d90 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
16da0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
16db0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
16dc0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
16dd0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
16de0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
16df0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
16e00 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
16e10 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
16e20 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
16e30 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
16e40 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
16e50 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
16e60 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
16e70 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
16e80 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
16e90 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
16ea0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
16eb0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
16ec0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
16ed0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
16ee0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
16ef0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
16f00 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
16f10 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
16f20 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
16f30 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
16f40 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
16f50 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
16f60 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
16f70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
16f80 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
16f90 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
16fa0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
16fb0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
16fc0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
16fd0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
16fe0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
16ff0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17000 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17020 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17030 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17040 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17050 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17060 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17070 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17080 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17090 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
170a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
170b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
170c0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
170d0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
170e0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
170f0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17100 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17110 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17120 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
17130 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
17140 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17150 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
17160 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17170 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
17180 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
17190 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
171a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
171b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
171c0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
171d0 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
171e0 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
171f0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
17200 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17210 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
17220 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
17230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17240 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
17250 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
17260 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
17270 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
17280 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
17290 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
172a0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
172b0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
172c0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
172d0 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
172e0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
172f0 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
17300 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
17310 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
17320 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
17330 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
17340 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
17350 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
17360 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
17370 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
17380 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
17390 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
173a0 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
173b0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
173c0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
173d0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
173e0 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
173f0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17400 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
17410 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
17420 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
17430 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
17440 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
17450 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
17460 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
17470 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
17480 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
17490 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
174a0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
174b0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
174c0 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
174d0 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
174e0 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
174f0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
17500 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
17510 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
17520 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
17530 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
17540 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
17550 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
17560 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
17570 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
17580 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
17590 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
175a0 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
175b0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
175c0 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
175d0 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
175e0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
175f0 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
17600 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
17610 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
17620 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
17630 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
17640 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
17650 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
17660 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
17670 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
17680 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
17690 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
176a0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
176b0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
176c0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
176d0 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
176e0 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
176f0 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
17700 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
17710 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
17720 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
17730 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
17740 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
17750 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
17760 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
17770 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
17780 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17790 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
177a0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
177b0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
177c0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
177d0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
177e0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
177f0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
17800 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
17810 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
17820 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
17830 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
17840 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17850 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
17860 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
17870 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
17880 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
17890 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
178a0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
178b0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
178c0 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
178d0 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
178e0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
178f0 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
17900 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
17910 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
17920 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
17930 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
17940 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
17950 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
17960 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
17970 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
17980 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
17990 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
179a0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
179b0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
179c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
179d0 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
179e0 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
179f0 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
17a00 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
17a10 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
17a20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
17a30 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17a40 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
17a50 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
17a60 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
17a70 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
17a80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
17a90 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
17aa0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
17ab0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
17ac0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
17ad0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
17ae0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
17af0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
17b00 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
17b10 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
17b20 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17b30 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
17b40 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
17b50 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
17b60 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
17b80 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
17b90 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
17ba0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17bb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
17bc0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
17bd0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
17be0 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
17bf0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
17c00 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
17c10 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
17c20 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
17c30 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
17c40 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
17c50 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17c60 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
17c70 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
17c80 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
17c90 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17ca0 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
17cb0 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
17cc0 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
17cd0 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
17ce0 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
17cf0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
17d00 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
17d10 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
17d20 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
17d30 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
17d40 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
17d50 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
17d60 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
17d70 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
17d80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
17d90 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
17da0 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
17db0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17dc0 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
17dd0 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
17de0 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
17df0 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
17e00 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
17e10 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
17e20 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
17e30 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17e40 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
17e50 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
17e60 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
17e70 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
17e80 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
17e90 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
17ea0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
17eb0 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
17ec0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
17ed0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
17ee0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
17ef0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
17f00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
17f10 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
17f20 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17f30 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
17f40 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
17f50 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
17f60 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17f70 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17f80 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
17f90 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
17fa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17fb0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
17fc0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17fd0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
17fe0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
17ff0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
18000 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18010 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18020 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
18030 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
18040 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
18050 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18060 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
18070 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
18080 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
18090 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
180a0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
180b0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
180c0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
180d0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
180e0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
180f0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
18100 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
18110 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
18120 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
18130 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
18140 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
18150 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
18160 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
18170 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
18180 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
18190 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
181a0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
181b0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
181c0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
181d0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
181e0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
181f0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
18200 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
18210 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
18220 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
18230 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
18240 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
18250 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
18260 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
18270 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
18280 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
18290 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
182a0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
182b0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
182c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
182d0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
182e0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
182f0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
18300 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
18310 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
18320 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
18330 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
18340 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
18350 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
18360 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
18370 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
18380 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
18390 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
183a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
183b0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
183c0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
183d0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
183e0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
183f0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
18400 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
18410 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
18420 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
18430 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
18440 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
18450 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
18460 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
18470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18480 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
18490 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
184a0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
184b0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
184c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
184d0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
184e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
184f0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
18500 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
18510 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
18520 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
18530 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18540 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
18550 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
18560 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
18570 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
18580 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
18590 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
185a0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
185b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
185c0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
185d0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
185e0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
185f0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18600 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
18610 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
18620 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
18630 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
18640 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18650 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
18660 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
18670 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
18680 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
18690 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
186a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
186b0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
186c0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
186d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
186e0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
186f0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
18700 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18710 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
18720 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
18730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18740 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
18750 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18760 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
18770 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
18780 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
18790 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
187a0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
187b0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
187c0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
187d0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
187e0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
187f0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
18800 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
18810 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
18820 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
18830 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
18840 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
18850 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
18860 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
18870 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
18880 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
18890 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
188a0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
188b0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
188c0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
188d0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
188e0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
188f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
18900 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
18910 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
18920 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
18930 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
18940 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
18950 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
18960 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
18970 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
18980 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
18990 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
189a0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
189b0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
189c0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
189d0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
189e0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
189f0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
18a00 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
18a10 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
18a20 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
18a30 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
18a40 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
18a50 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
18a60 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
18a70 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
18a80 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
18a90 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
18aa0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
18ab0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
18ac0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
18ad0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
18ae0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
18af0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
18b00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
18b10 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
18b20 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
18b30 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
18b40 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
18b50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
18b60 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
18b70 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
18b80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
18b90 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
18ba0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
18bb0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
18bc0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
18bd0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
18be0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
18bf0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
18c00 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
18c10 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
18c20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
18c30 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
18c40 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
18c50 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18c60 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
18c70 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
18c80 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
18c90 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
18ca0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18cb0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
18cc0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
18cd0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
18ce0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
18cf0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18d00 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
18d10 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
18d20 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
18d30 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
18d40 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
18d50 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
18d60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
18d70 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
18d80 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
18d90 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
18da0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
18db0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
18dc0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
18dd0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
18de0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
18df0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
18e00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
18e10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
18e20 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
18e30 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
18e40 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ql);.SQLITE_API 
18e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
18e60 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
18e70 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
18e80 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
18e90 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
18ea0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
18eb0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
18ec0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
18ed0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
18ee0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
18ef0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18f00 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
18f10 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
18f20 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
18f30 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
18f40 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
18f50 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
18f60 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
18f70 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
18f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18f90 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
18fa0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
18fb0 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
18fc0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
18fd0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
18fe0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
18ff0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
19000 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
19010 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19020 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
19030 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
19040 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
19050 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
19060 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
19070 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
19080 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
19090 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
190a0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
190b0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
190c0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
190d0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
190e0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
190f0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
19100 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
19110 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
19120 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
19130 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
19140 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
19150 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
19160 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
19170 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
19180 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19190 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
191a0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
191b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
191c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
191d0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
191e0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
191f0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
19200 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
19210 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
19220 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
19230 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
19240 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
19250 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
19260 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
19270 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
19280 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
19290 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
192a0 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
192b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
192c0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
192d0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
192e0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
192f0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
19300 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
19310 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
19320 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
19330 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
19340 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
19350 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
19360 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
19370 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
19380 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
19390 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
193a0 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
193b0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
193c0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
193d0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
193e0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
193f0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
19400 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
19410 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
19420 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
19430 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
19440 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
19450 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
19460 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
19470 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
19480 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
19490 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
194a0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
194b0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
194c0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
194d0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
194e0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
194f0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
19500 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
19510 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
19520 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
19530 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
19540 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
19550 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
19560 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
19570 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
19580 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
19590 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
195a0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
195b0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
195c0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
195d0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
195e0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
195f0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
19600 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
19610 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
19620 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
19630 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
19640 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
19650 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
19660 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
19670 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
19680 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
19690 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
196a0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
196b0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
196c0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
196d0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
196e0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
196f0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
19700 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
19710 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
19720 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
19730 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
19740 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
19750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19760 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
19770 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
19780 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
19790 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
197a0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
197b0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
197c0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
197d0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
197e0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
197f0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
19800 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
19810 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
19820 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
19830 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
19840 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
19850 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
19860 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
19870 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
19880 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
19890 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
198a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
198b0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
198c0 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
198d0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
198e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
198f0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
19900 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
19910 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
19920 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
19930 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
19940 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
19950 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
19960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
19970 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
19980 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
19990 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
199a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
199b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
199c0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
199d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
199e0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
199f0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
19a00 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
19a10 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
19a20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
19a30 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
19a40 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
19a50 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
19a60 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
19a70 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
19a80 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
19a90 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
19aa0 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
19ab0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
19ac0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
19ad0 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
19ae0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
19af0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
19b00 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
19b10 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
19b20 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
19b30 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
19b40 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
19b50 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
19b60 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
19b70 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
19b80 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
19b90 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
19ba0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
19bb0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
19bc0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
19bd0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
19be0 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
19bf0 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
19c00 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
19c10 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
19c20 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
19c30 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
19c40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19c50 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20  n] at any given 
19c60 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
19c70 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
19c80 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
19c90 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
19ca0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
19cb0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
19cc0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
19cd0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
19ce0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
19cf0 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  leared.)^.**.** 
19d00 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47  See also:  [PRAG
19d10 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
19d20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
19d30 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19d40 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
19d50 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
19d60 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
19d70 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
19d80 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
19d90 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
19da0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
19db0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
19dc0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
19dd0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
19de0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
19df0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19e00 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
19e10 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
19e20 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
19e30 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
19e40 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
19e50 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
19e60 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
19e70 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
19e80 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
19e90 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
19ea0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
19eb0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
19ec0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
19ed0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
19ee0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
19ef0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
19f00 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
19f10 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
19f20 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
19f30 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
19f40 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
19f50 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
19f60 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
19f70 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
19f80 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
19f90 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
19fa0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
19fb0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
19fc0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19fd0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
19fe0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
19ff0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1a000 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1a010 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1a020 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1a030 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1a040 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1a050 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1a060 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1a070 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1a080 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1a090 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1a0a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1a0b0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1a0c0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1a0d0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1a0e0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1a0f0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1a100 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1a110 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1a120 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1a130 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1a140 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1a150 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1a160 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1a170 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1a180 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1a190 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1a1a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1a1b0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1a1c0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1a1d0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1a1e0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1a1f0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1a200 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1a210 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1a220 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1a230 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1a240 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1a250 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1a260 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1a270 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1a280 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1a290 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1a2a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a2b0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1a2c0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1a2d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1a2e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a2f0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1a300 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1a310 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1a320 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1a330 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1a340 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1a350 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a360 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1a370 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1a380 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1a390 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1a3a0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1a3b0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1a3c0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1a3d0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1a3e0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1a3f0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1a400 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1a410 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1a420 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1a430 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a440 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a450 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1a460 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a470 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1a480 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a490 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1a4a0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1a4b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1a4c0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1a4d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a4e0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1a4f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a500 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1a510 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a520 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1a530 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1a540 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1a550 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1a560 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1a570 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a580 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1a590 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1a5a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1a5b0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1a5c0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1a5d0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1a5e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1a5f0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1a600 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1a610 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1a620 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1a630 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1a640 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1a650 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1a660 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1a670 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1a680 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1a690 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1a6a0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1a6b0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1a6c0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1a6d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1a6e0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1a6f0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1a700 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1a710 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1a720 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1a730 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1a740 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1a750 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1a760 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a770 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1a780 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1a790 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1a7a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a7b0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1a7c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1a7d0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1a7e0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1a7f0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1a800 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1a810 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a820 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1a830 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1a840 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1a850 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1a860 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1a870 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1a880 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1a890 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1a8a0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1a8b0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1a8c0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1a8d0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1a8e0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1a8f0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1a900 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1a910 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1a920 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1a930 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1a940 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1a950 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1a960 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1a970 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1a980 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1a990 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1a9a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1a9b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1a9c0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
1a9d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1a9e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1a9f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1aa00 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1aa10 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1aa20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1aa30 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1aa40 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1aa50 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1aa60 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1aa70 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1aa80 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1aa90 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1aaa0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1aab0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1aac0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1aad0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1aae0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1aaf0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1ab00 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1ab10 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1ab20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1ab30 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1ab40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1ab50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1ab60 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1ab70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ab80 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1ab90 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1aba0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1abb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1abc0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1abd0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1abe0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1abf0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1ac00 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1ac10 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1ac20 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1ac30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1ac40 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1ac50 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1ac60 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1ac70 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1ac80 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1ac90 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1aca0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1acb0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1acc0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1acd0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1ace0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1acf0 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1ad00 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1ad10 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1ad20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1ad30 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1ad40 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1ad50 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1ad60 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1ad70 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1ad80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ad90 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1ada0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1adb0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1adc0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1add0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1ade0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1adf0 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1ae00 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1ae10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1ae20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1ae30 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1ae40 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1ae50 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1ae60 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1ae70 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1ae80 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1ae90 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1aea0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1aeb0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1aec0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1aed0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1aee0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1aef0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1af00 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1af10 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1af20 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1af30 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1af40 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1af50 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1af60 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1af70 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1af80 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1af90 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1afa0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1afb0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1afc0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1afd0 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1afe0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1aff0 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1b000 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1b010 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1b020 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b030 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1b040 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1b050 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1b060 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1b070 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1b080 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1b090 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b0a0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1b0b0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1b0c0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1b0d0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1b0e0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1b0f0 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1b100 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1b110 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1b120 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1b130 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1b140 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1b150 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1b160 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1b170 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1b180 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1b190 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1b1a0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1b1b0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1b1c0 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1b1d0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1b1e0 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1b1f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b200 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1b210 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1b220 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1b230 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1b240 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1b250 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1b260 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1b270 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1b280 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b290 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1b2a0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1b2b0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1b2c0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1b2d0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1b2e0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1b2f0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1b300 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1b310 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1b320 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1b330 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1b340 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1b350 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1b360 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1b370 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1b380 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1b390 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1b3a0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1b3b0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1b3c0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1b3d0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1b3e0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1b3f0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1b400 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1b410 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1b420 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1b430 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1b440 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1b450 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1b460 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b470 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b480 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1b490 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1b4a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b4b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1b4c0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1b4d0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1b4e0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1b4f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b500 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b510 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1b520 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1b530 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1b540 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1b550 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1b560 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1b570 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1b580 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1b590 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1b5a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b5b0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1b5c0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1b5d0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1b5e0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1b5f0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1b600 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1b610 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1b620 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b630 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b640 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b650 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b660 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b670 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1b680 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b690 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1b6a0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1b6b0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1b6c0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1b6d0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1b6e0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1b6f0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b700 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b710 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b720 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1b730 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1b740 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b750 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1b760 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1b770 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1b780 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1b790 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1b7a0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1b7b0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1b7c0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1b7d0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1b7e0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1b7f0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1b800 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1b810 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1b820 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1b830 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1b840 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1b850 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1b860 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1b870 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1b880 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1b890 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1b8a0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1b8b0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1b8c0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1b8d0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1b8e0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1b8f0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1b900 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1b910 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b920 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1b930 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1b940 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1b950 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1b960 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1b970 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1b980 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1b990 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1b9a0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1b9b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b9c0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1b9d0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1b9e0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1b9f0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1ba00 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1ba10 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1ba20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1ba30 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1ba40 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1ba50 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1ba60 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1ba70 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1ba80 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1ba90 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1baa0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1bab0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1bac0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1bad0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1bae0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1baf0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1bb00 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1bb10 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1bb20 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1bb30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1bb40 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1bb50 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1bb60 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49  , va_list);.SQLI
1bb70 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1bb80 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1bb90 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1bba0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
1bbb0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1bbc0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1bbd0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1bbe0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1bbf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bc00 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1bc10 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1bc20 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1bc30 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1bc40 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1bc50 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1bc60 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1bc70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1bc80 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1bc90 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1bca0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1bcb0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1bcc0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1bcd0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1bce0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1bcf0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1bd00 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1bd10 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1bd20 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1bd30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1bd40 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1bd50 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1bd60 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1bd70 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1bd80 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1bd90 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1bda0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1bdb0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1bdc0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1bdd0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1bde0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1bdf0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1be00 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1be10 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1be20 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1be30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1be40 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1be50 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1be60 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1be70 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1be80 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1be90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1bea0 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1beb0 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1bec0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1bed0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1bee0 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1bef0 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1bf00 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1bf10 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1bf20 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1bf30 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1bf40 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1bf50 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1bf60 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1bf70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1bf80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bf90 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1bfa0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1bfb0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1bfc0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1bfd0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1bfe0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1bff0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1c000 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1c010 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1c020 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1c030 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c040 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1c050 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1c060 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1c070 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1c080 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1c090 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1c0a0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1c0b0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1c0c0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1c0d0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1c0e0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1c0f0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1c100 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1c110 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1c120 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1c130 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1c140 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1c150 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1c160 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1c170 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1c180 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1c190 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1c1a0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1c1b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1c1c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c1d0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1c1e0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1c1f0 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1c200 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1c210 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1c220 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c230 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1c240 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1c250 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1c260 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1c270 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1c280 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1c290 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1c2a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1c2b0 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1c2c0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1c2d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c2e0 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1c2f0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1c300 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1c310 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1c320 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1c330 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1c340 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1c350 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1c360 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1c370 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1c380 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1c390 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1c3a0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1c3b0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1c3c0 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1c3d0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1c3e0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1c3f0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1c400 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1c410 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1c420 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1c430 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1c440 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1c450 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1c460 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1c470 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1c480 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1c490 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1c4a0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1c4b0 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1c4c0 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1c4d0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1c4e0 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1c4f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1c500 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1c510 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1c520 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1c530 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1c540 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1c550 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1c560 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1c570 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1c580 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1c590 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1c5a0 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1c5b0 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1c5c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1c5d0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1c5e0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1c5f0 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1c600 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1c610 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c620 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1c630 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1c640 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1c650 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1c660 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1c670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c680 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1c690 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1c6a0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1c6b0 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1c6c0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1c6d0 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1c6e0 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1c6f0 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1c700 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1c710 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1c720 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1c730 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1c740 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1c750 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1c760 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1c770 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1c780 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1c790 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1c7a0 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1c7b0 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1c7c0 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1c7d0 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1c7e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1c7f0 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1c800 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1c810 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1c820 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1c830 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1c840 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1c850 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1c860 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1c870 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c880 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1c890 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1c8a0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1c8b0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1c8c0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1c8d0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1c8e0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1c8f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1c900 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1c910 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1c920 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1c930 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1c940 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c950 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1c960 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1c970 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1c980 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1c990 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1c9a0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1c9b0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1c9c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c9d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1c9e0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1c9f0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1ca00 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1ca10 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1ca20 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1ca30 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1ca40 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1ca50 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1ca60 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1ca70 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1ca80 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1ca90 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1caa0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1cab0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1cac0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1cad0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1cae0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1caf0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1cb00 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1cb10 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1cb20 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1cb30 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1cb40 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1cb50 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1cb60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1cb70 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1cb80 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1cb90 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1cba0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1cbb0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1cbc0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1cbd0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1cbe0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1cbf0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1cc00 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1cc10 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1cc20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1cc30 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1cc40 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1cc50 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1cc60 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1cc70 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1cc80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cc90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1cca0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1ccb0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1ccc0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1ccd0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1cce0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1ccf0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1cd00 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1cd10 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1cd20 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1cd30 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1cd40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1cd50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1cd60 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1cd70 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1cd80 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1cd90 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1cda0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1cdb0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1cdc0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1cdd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1cde0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1cdf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1ce00 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1ce10 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
1ce20 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c  te3_uint64);.SQL
1ce30 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1ce40 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1ce50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1ce60 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1ce70 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1ce80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ce90 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1cea0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1ceb0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1cec0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1ced0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1cee0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1cef0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1cf00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1cf10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1cf20 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1cf30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1cf40 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1cf50 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1cf60 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1cf70 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1cf80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1cf90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1cfa0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1cfb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1cfc0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1cfd0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1cfe0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1cff0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1d000 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1d010 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d020 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1d030 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1d040 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1d050 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d060 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1d070 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1d080 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1d090 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1d0a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1d0b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d0c0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1d0d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d0e0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1d0f0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1d100 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1d110 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1d120 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1d130 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1d140 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1d150 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1d160 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1d170 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1d180 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1d190 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d1a0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1d1b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1d1c0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1d1d0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1d1e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1d1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1d200 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1d210 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1d220 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1d230 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d240 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1d250 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1d260 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1d270 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1d280 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1d290 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1d2a0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1d2b0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
1d2c0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1d2d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1d2e0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1d2f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1d300 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1d310 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d320 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1d330 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1d340 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1d350 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1d360 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1d370 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1d380 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1d390 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1d3a0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1d3b0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1d3c0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1d3d0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1d3e0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1d3f0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1d400 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1d410 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1d420 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1d430 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1d440 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1d450 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1d460 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1d470 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1d480 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1d490 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1d4a0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1d4b0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1d4c0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1d4d0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1d4e0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1d4f0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1d500 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1d510 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1d520 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 4e 20 69 73  r P..** ^If N is
1d530 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20   less than one, 
1d540 74 68 65 6e 20 50 20 63 61 6e 20 62 65 20 61 20  then P can be a 
1d550 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1d560 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75  .** ^If this rou
1d570 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65  tine has not bee
1d580 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c  n previously cal
1d590 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72  led or if the pr
1d5a0 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68  evious.** call h
1d5b0 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f  ad N less than o
1d5c0 6e 65 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e  ne, then the PRN
1d5d0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
1d5e0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20  g randomness.** 
1d5f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
1d600 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1d610 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
1d620 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1d630 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1d640 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1d650 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1d660 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1d670 20 6f 72 20 6d 6f 72 65 20 74 68 65 6e 0a 2a 2a   or more then.**
1d680 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1d690 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1d6a0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1d6b0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1d6c0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1d6d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1d6e0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1d6f0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
1d700 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
1d710 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1d720 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1d730 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1d740 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1d750 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1d760 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1d770 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1d780 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d790 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1d7a0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1d7b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1d7c0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1d7d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1d7e0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1d7f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d800 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1d810 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1d820 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1d830 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1d840 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1d850 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1d860 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1d870 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d880 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1d890 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1d8a0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1d8b0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1d8c0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1d8d0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1d8e0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1d8f0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1d900 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1d910 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1d920 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d930 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1d940 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1d950 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1d960 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1d970 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1d980 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1d990 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1d9a0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1d9b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1d9c0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1d9d0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1d9e0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1d9f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1da00 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1da10 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1da20 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1da30 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1da40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1da50 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1da60 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1da70 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1da80 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1da90 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1daa0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1dab0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1dac0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1dad0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1dae0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1daf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1db00 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1db10 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1db20 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1db30 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1db40 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1db50 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1db60 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1db70 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1db80 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1db90 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1dba0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1dbb0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1dbc0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1dbd0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1dbe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1dbf0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1dc00 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1dc10 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1dc20 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1dc30 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1dc40 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1dc50 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1dc60 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1dc70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1dc80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1dc90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1dca0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1dcb0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1dcc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1dcd0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1dce0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1dcf0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1dd00 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1dd10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1dd20 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1dd30 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1dd40 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1dd50 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1dd60 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1dd70 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1dd80 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1dd90 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1dda0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1ddb0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1ddc0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1ddd0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1dde0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1ddf0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1de00 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1de10 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1de20 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1de30 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1de40 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1de50 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1de60 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1de70 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1de80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1de90 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1dea0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1deb0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1dec0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1ded0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1dee0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1def0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1df00 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1df10 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1df20 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1df30 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1df40 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1df50 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1df60 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1df70 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1df80 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1df90 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1dfa0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1dfb0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1dfc0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1dfd0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1dfe0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1dff0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1e000 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1e010 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1e020 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1e030 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1e040 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1e050 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1e060 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1e070 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1e080 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1e090 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1e0a0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1e0b0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1e0c0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1e0d0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1e0e0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1e0f0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1e100 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1e110 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1e120 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1e130 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1e140 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1e150 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1e160 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1e170 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1e180 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1e190 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1e1a0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1e1b0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1e1c0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1e1d0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1e1e0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1e1f0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1e200 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1e210 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1e220 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1e230 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1e240 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1e250 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1e260 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1e270 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1e280 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1e290 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1e2a0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1e2b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1e2c0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1e2d0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1e2e0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1e2f0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1e300 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1e310 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1e320 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1e330 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1e340 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1e350 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1e360 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1e370 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1e380 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1e390 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1e3a0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1e3b0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1e3c0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1e3d0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1e3e0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1e3f0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1e400 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1e410 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1e420 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1e430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e440 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1e450 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1e460 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e470 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1e480 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1e490 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1e4a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e4b0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1e4c0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1e4d0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1e4e0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1e4f0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1e500 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e510 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1e520 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1e530 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1e540 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e550 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1e560 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1e570 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1e580 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1e590 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e5a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1e5b0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1e5c0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1e5d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1e5e0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1e5f0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1e600 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1e610 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1e620 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e630 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1e640 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1e650 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1e660 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1e670 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1e680 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e690 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1e6a0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1e6b0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1e6c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1e6d0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1e6e0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1e6f0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1e700 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1e710 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1e720 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1e730 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1e740 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e750 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1e760 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1e770 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e780 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1e790 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1e7a0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1e7b0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1e7c0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1e7d0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1e7e0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1e7f0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1e800 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1e810 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1e820 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1e830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e840 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1e850 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1e860 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1e870 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1e880 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
1e890 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1e8a0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1e8b0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1e8c0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1e8d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e8e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e8f0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1e900 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1e910 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e920 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1e930 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e940 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e950 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1e960 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e970 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1e980 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1e990 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1e9a0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1e9b0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1e9c0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1e9d0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e9e0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1e9f0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1ea00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1ea10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1ea20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1ea30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1ea40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1ea50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1ea60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1ea70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1ea80 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
1ea90 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
1eaa0 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
1eab0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1eac0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1ead0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1eae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eaf0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1eb00 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1eb10 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1eb20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1eb30 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1eb40 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1eb50 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1eb60 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1eb70 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1eb80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1eb90 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1eba0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1ebb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ebc0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1ebd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1ebe0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1ebf0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1ec00 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1ec10 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1ec20 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1ec30 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1ec40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1ec50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1ec60 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1ec70 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1ec80 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1ec90 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1eca0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1ecb0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1ecc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1ecd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ece0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1ecf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1ed00 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1ed10 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1ed20 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1ed30 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1ed40 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1ed50 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1ed60 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1ed70 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1ed80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1ed90 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1eda0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1edb0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1edc0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1edd0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1ede0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1edf0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1ee00 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1ee10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ee20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1ee30 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1ee40 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1ee50 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1ee60 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1ee70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ee80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ee90 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1eea0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1eeb0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1eec0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1eed0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1eee0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1eef0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1ef00 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1ef10 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1ef20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1ef30 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ef40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ef50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ef60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1ef70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1ef80 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1ef90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1efa0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1efb0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1efc0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1efd0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1efe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1eff0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1f000 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1f010 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f020 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f030 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f040 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1f050 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1f060 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f070 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f080 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f090 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1f0a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1f0b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f0c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f0d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f0e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1f0f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f100 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f110 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f120 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f130 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1f140 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f150 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f160 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f170 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1f180 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1f190 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f1a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f1b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f1c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1f1d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1f1e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f1f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f200 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f210 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1f220 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1f230 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f240 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f250 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f260 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1f270 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1f280 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f290 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f2a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f2b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1f2c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1f2d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f2e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f2f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f300 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1f310 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1f320 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f330 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f350 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1f360 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1f370 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f380 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f3a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1f3b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1f3c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f3d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f3e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f3f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1f400 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1f410 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f420 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f440 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1f450 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1f460 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f470 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f490 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1f4a0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1f4b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f4c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f4d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1f4e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1f4f0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1f500 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f510 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f520 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1f530 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1f540 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1f550 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1f560 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1f570 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1f580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f590 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1f5a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f5b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f5c0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1f5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1f5e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f5f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f600 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f610 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1f620 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1f630 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1f640 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f650 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f660 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1f670 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1f680 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f690 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f6a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f6b0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1f6c0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1f6d0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1f6e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f6f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f700 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1f710 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1f720 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f730 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f740 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f750 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1f760 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1f770 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1f780 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f7a0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1f7b0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1f7c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f7d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f7e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f7f0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1f800 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1f810 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f820 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f840 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1f850 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1f860 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f870 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f890 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1f8a0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1f8b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1f8c0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1f8d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1f8e0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1f8f0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1f900 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1f910 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1f920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1f930 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1f940 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1f950 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1f960 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1f970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1f980 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1f990 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1f9a0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
1f9b0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
1f9c0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
1f9d0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
1f9e0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1f9f0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
1fa00 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1fa10 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1fa20 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1fa30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1fa40 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1fa50 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1fa60 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1fa70 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1fa80 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1fa90 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1faa0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1fab0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1fac0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1fad0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1fae0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1faf0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1fb00 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1fb10 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1fb20 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1fb30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1fb40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1fb50 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1fb60 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1fb70 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1fb80 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1fb90 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1fba0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1fbb0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1fbc0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1fbd0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1fbe0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1fbf0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1fc00 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1fc10 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1fc20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1fc30 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1fc40 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1fc50 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1fc60 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1fc70 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1fc80 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
1fc90 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
1fca0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
1fcb0 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
1fcc0 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
1fcd0 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
1fce0 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
1fcf0 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
1fd00 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
1fd10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
1fd20 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1fd30 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1fd40 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1fd50 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1fd60 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1fd70 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1fd80 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1fd90 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1fda0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1fdb0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1fdc0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1fdd0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1fde0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1fdf0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1fe00 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1fe10 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1fe20 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1fe30 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1fe40 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1fe50 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1fe60 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1fe70 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1fe80 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1fe90 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1fea0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1feb0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1fec0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1fed0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1fee0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1fef0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1ff00 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1ff10 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1ff20 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1ff30 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1ff40 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1ff50 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1ff60 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1ff70 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1ff80 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1ff90 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1ffa0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1ffb0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
1ffc0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1ffd0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1ffe0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1fff0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
20000 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
20010 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
20020 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
20030 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
20040 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
20050 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
20060 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
20070 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
20080 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
20090 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
200a0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
200b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
200c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
200d0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
200e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
200f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
20100 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
20110 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
20120 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
20130 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
20140 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
20150 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
20160 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
20170 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
20180 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
20190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
201a0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
201b0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
201c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
201d0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
201e0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
201f0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
20200 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
20210 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
20220 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
20230 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
20240 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
20250 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
20260 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
20270 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
20280 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
20290 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
202a0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
202b0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
202c0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
202d0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
202e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
202f0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
20300 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
20310 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
20320 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
20330 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
20340 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
20350 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
20360 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
20370 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
20380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20390 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
203a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
203b0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
203c0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
203d0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
203e0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
203f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
20400 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
20410 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
20420 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
20430 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
20440 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
20450 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
20460 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
20470 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20480 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
20490 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
204a0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
204b0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
204c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
204d0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
204e0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
204f0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
20500 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
20510 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
20520 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
20530 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
20540 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
20550 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
20560 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
20570 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
20580 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
20590 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
205a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
205b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
205c0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
205d0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
205e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
205f0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
20600 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
20610 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
20620 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
20630 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
20640 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
20650 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
20660 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
20670 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20680 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
20690 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
206a0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
206b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
206c0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
206d0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
206e0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
206f0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
20700 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
20710 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
20720 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
20730 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
20740 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20750 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20760 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
20770 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
20780 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
20790 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
207a0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
207b0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
207c0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
207d0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
207e0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
207f0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
20800 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
20810 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
20820 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
20830 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
20840 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
20850 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
20860 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
20870 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
20880 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
20890 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
208a0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
208b0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
208c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
208d0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
208e0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
208f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
20900 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
20910 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
20920 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
20930 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
20940 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
20950 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
20960 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
20970 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
20980 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
20990 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
209a0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
209b0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
209c0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
209d0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
209e0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
209f0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
20a00 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
20a10 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
20a20 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
20a30 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
20a40 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
20a50 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
20a60 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
20a70 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
20a80 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
20a90 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
20aa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20ab0 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
20ac0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
20ad0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
20ae0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
20af0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
20b00 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
20b10 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
20b20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
20b30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
20b40 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20b50 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
20b60 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
20b70 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
20b80 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
20b90 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
20ba0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
20bb0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
20bc0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
20bd0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
20be0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
20bf0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
20c00 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
20c10 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
20c20 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
20c30 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
20c40 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
20c50 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
20c60 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
20c70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
20c80 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
20c90 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
20ca0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
20cb0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
20cc0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
20cd0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
20ce0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
20cf0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
20d00 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20d10 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20d20 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
20d30 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20d40 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
20d50 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
20d60 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
20d70 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20d80 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
20d90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20da0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20db0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
20dc0 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
20dd0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
20de0 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
20df0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
20e00 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
20e10 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20e20 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
20e30 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20e40 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20e50 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
20e60 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
20e70 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
20e80 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
20e90 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
20ea0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
20eb0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20ec0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
20ed0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
20ee0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
20ef0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
20f00 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
20f10 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20f20 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20f30 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20f40 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
20f50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
20f60 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20f70 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20f80 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
20f90 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
20fa0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
20fb0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
20fc0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
20fd0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
20fe0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
20ff0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
21000 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
21010 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
21020 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
21030 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
21040 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21050 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
21060 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
21070 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
21080 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
21090 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
210a0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
210b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
210c0 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
210d0 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
210e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
210f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
21100 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
21110 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
21120 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
21130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21140 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
21150 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
21160 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
21170 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
21180 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
21190 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
211a0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
211b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
211c0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
211d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
211e0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
211f0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
21200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21210 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
21220 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
21230 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
21240 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
21250 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
21260 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
21270 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
21280 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21290 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
212a0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
212b0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
212c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
212d0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
212e0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
212f0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
21300 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
21310 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
21320 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
21330 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
21340 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
21350 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
21360 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
21370 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21380 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
21390 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
213a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
213b0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
213c0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
213d0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
213e0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
213f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
21400 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
21410 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21420 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
21430 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
21440 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
21450 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
21460 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
21470 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
21480 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
21490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
214a0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
214b0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
214c0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
214d0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
214e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
214f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
21500 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
21510 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
21520 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
21530 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
21540 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
21550 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
21560 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
21570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
21580 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
21590 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
215a0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
215b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
215c0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
215d0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
215e0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
215f0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
21600 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
21610 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
21620 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
21630 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
21640 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
21650 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
21660 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
21670 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
21680 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
21690 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
216a0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
216b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
216c0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
216d0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
216e0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
216f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
21700 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
21710 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
21720 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
21730 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
21740 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
21750 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
21760 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
21770 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
21780 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
21790 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
217a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
217b0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
217c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
217d0 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
217e0 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
217f0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
21800 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
21810 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
21820 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
21830 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
21840 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21850 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
21860 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
21870 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
21880 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
21890 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
218a0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
218b0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
218c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
218d0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
218e0 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
218f0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
21900 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21910 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
21920 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
21930 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
21940 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
21950 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
21960 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
21970 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
21980 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
21990 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
219a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
219b0 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
219c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
219d0 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
219e0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
219f0 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
21a00 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
21a10 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
21a20 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
21a30 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
21a40 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
21a50 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
21a60 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
21a70 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
21a80 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
21a90 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
21aa0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
21ab0 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
21ac0 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
21ad0 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
21ae0 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
21af0 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
21b00 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
21b10 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
21b20 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
21b30 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
21b40 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
21b50 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
21b60 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
21b70 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
21b80 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
21b90 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
21ba0 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
21bb0 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
21bc0 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
21bd0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
21be0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
21bf0 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
21c00 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
21c10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
21c20 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
21c30 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
21c40 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
21c50 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
21c60 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
21c70 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
21c80 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21c90 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
21ca0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
21cb0 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
21cc0 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
21cd0 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
21ce0 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
21cf0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
21d00 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
21d10 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
21d20 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
21d30 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
21d40 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
21d50 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
21d60 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
21d70 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
21d80 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
21d90 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
21da0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
21db0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
21dc0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
21dd0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21de0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
21df0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
21e00 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
21e10 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
21e20 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
21e30 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
21e40 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
21e50 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
21e60 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
21e70 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
21e80 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
21e90 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
21ea0 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
21eb0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
21ec0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
21ed0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
21ee0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
21ef0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
21f00 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
21f10 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
21f20 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
21f30 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
21f40 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
21f50 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
21f60 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
21f70 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
21f80 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
21f90 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
21fa0 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
21fb0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
21fc0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
21fd0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
21fe0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
21ff0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
22000 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
22010 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
22020 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
22030 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
22040 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
22050 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
22060 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
22070 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
22080 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
22090 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
220a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
220b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
220c0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
220d0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
220e0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
220f0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22100 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
22110 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
22120 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
22130 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
22140 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
22150 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
22160 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
22170 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22180 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22190 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
221a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
221b0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
221c0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
221d0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
221e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
221f0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
22200 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
22210 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
22220 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
22230 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
22240 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
22250 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
22260 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
22270 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
22280 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
22290 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
222a0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
222b0 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
222c0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
222d0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
222e0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
222f0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
22300 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
22310 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
22320 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
22330 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
22340 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
22350 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
22360 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
22370 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
22380 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
22390 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
223a0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
223b0 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
223c0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
223d0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
223e0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
223f0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
22400 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
22410 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
22420 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
22430 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
22440 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
22450 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
22460 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
22470 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
22480 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22490 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
224a0 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
224b0 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
224c0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
224d0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
224e0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
224f0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
22500 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
22510 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
22520 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
22530 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
22540 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22550 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
22560 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
22570 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
22580 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22590 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
225a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
225b0 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
225c0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
225d0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
225e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
225f0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
22600 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
22610 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
22620 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
22630 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
22640 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
22650 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
22660 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
22670 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
22680 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
22690 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
226a0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
226b0 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
226c0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
226d0 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
226e0 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
226f0 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
22700 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
22710 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
22720 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
22730 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
22740 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
22750 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
22760 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
22770 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
22780 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
22790 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
227a0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
227b0 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
227c0 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
227d0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
227e0 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
227f0 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
22800 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
22810 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
22820 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
22830 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
22840 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
22850 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
22860 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
22870 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
22880 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
22890 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
228a0 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
228b0 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
228c0 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
228d0 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
228e0 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
228f0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
22900 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
22910 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
22920 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
22930 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
22940 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
22950 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
22960 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
22970 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
22980 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
22990 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
229a0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
229b0 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
229c0 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
229d0 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
229e0 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
229f0 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
22a00 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
22a10 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
22a20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
22a30 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
22a40 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
22a50 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
22a60 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
22a70 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22a80 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
22a90 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
22aa0 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
22ab0 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
22ac0 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
22ad0 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
22ae0 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
22af0 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
22b00 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
22b10 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
22b20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
22b30 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
22b40 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
22b50 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
22b60 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
22b70 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
22b80 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
22b90 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
22ba0 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
22bb0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
22bc0 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
22bd0 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
22be0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22bf0 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
22c00 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
22c10 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22c20 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
22c30 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
22c40 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
22c50 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
22c60 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
22c70 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
22c80 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
22c90 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
22ca0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22cb0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
22cc0 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
22cd0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
22ce0 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
22cf0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
22d00 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
22d10 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
22d20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
22d30 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
22d40 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
22d50 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
22d60 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
22d70 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
22d80 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
22d90 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
22da0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22db0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
22dc0 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
22dd0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
22de0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
22df0 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
22e00 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
22e10 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
22e20 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
22e30 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
22e40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22e50 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
22e60 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
22e70 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
22e80 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
22e90 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
22ea0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
22eb0 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
22ec0 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
22ed0 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
22ee0 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
22ef0 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
22f00 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
22f10 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
22f20 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
22f30 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
22f40 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
22f50 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
22f60 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
22f70 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
22f80 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
22f90 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
22fa0 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
22fb0 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
22fc0 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
22fd0 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
22fe0 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
22ff0 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
23000 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
23010 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
23020 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
23030 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
23040 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23050 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
23060 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
23070 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23080 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
23090 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
230a0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
230b0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
230c0 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
230d0 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
230e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
230f0 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
23100 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
23110 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
23120 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
23130 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
23140 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
23150 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
23160 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
23170 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
23180 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
23190 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
231a0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
231b0 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
231c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
231d0 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
231e0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
231f0 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
23200 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
23210 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
23220 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
23230 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
23240 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
23250 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
23260 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
23270 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
23280 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
23290 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
232a0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
232b0 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
232c0 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
232d0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
232e0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
232f0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
23300 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
23310 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
23320 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
23330 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
23340 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
23350 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
23360 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
23370 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
23380 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
23390 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
233a0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
233b0 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
233c0 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
233d0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
233e0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
233f0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
23400 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
23410 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
23420 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
23430 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
23440 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
23450 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
23460 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
23470 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
23480 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
23490 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
234a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
234b0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
234c0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
234d0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
234e0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
234f0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23500 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
23510 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
23520 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
23530 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
23540 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
23550 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
23560 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
23570 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
23580 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
23590 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
235a0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
235b0 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
235c0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
235d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
235e0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
235f0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
23600 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
23610 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
23620 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
23630 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
23640 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
23650 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
23660 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
23670 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23680 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
23690 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
236a0 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
236b0 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
236c0 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
236d0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
236e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
236f0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
23700 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
23710 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
23720 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
23730 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23740 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23750 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
23760 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
23770 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
23780 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
23790 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
237a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
237b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
237c0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
237d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
237e0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
237f0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
23800 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23810 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23820 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
23830 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23840 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
23850 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
23860 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23870 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
23880 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
23890 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
238a0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
238b0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
238c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
238d0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
238e0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
238f0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
23900 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
23910 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
23920 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
23930 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
23940 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
23950 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
23960 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
23970 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
23980 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
23990 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
239a0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
239b0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
239c0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
239d0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
239e0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
239f0 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
23a00 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
23a10 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
23a20 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
23a30 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23a40 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
23a50 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
23a60 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
23a70 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
23a80 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
23a90 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
23aa0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
23ab0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
23ac0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
23ad0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
23ae0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
23af0 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
23b00 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
23b10 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
23b20 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
23b30 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23b40 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23b50 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
23b60 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
23b70 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
23b80 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
23b90 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
23ba0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
23bb0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23bc0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
23bd0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23be0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
23bf0 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
23c00 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
23c10 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
23c20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
23c30 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
23c40 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
23c50 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
23c60 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23c70 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
23c80 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
23c90 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
23ca0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
23cb0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
23cc0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
23cd0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
23ce0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
23cf0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23d00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
23d10 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
23d20 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
23d30 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
23d40 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
23d50 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
23d60 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
23d70 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
23d80 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
23d90 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
23da0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
23db0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23dc0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
23dd0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
23de0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
23df0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23e00 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
23e10 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
23e20 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
23e30 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
23e40 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
23e50 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
23e60 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
23e70 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
23e80 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
23e90 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
23ea0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
23eb0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
23ec0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
23ed0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23ee0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
23ef0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23f00 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
23f10 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
23f20 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
23f30 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
23f40 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
23f50 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
23f60 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
23f70 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
23f80 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
23f90 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
23fa0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
23fb0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
23fc0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
23fd0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
23fe0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
23ff0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
24000 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24010 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24020 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
24030 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24040 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
24050 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
24060 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
24070 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
24080 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
24090 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
240a0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
240b0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
240c0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
240d0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
240e0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
240f0 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
24100 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
24110 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
24120 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
24130 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24140 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
24150 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
24160 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
24170 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
24180 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24190 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
241a0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
241b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
241c0 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
241d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
241e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
241f0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
24200 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
24210 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
24220 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
24230 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
24240 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
24250 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
24260 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
24270 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24280 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
24290 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
242a0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
242b0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
242c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
242d0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
242e0 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
242f0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
24300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24310 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
24320 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
24330 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
24340 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
24350 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
24360 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
24370 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
24380 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
24390 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
243a0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
243b0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
243c0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
243d0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
243e0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
243f0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
24400 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
24410 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
24420 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
24430 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
24440 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
24450 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
24460 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
24470 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
24480 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
24490 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
244a0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
244b0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
244c0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
244d0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
244e0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
244f0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
24500 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
24510 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
24520 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
24530 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
24540 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
24550 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
24560 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
24570 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
24580 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
24590 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
245a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
245b0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
245c0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
245d0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
245e0 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
245f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24600 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
24610 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
24620 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
24630 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
24640 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
24650 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
24660 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
24670 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
24680 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
24690 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
246a0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
246b0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
246c0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
246d0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
246e0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
246f0 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
24700 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
24710 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
24720 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
24730 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
24740 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
24750 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
24760 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
24770 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
24780 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
24790 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
247a0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
247b0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
247c0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
247d0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
247e0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
247f0 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
24800 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
24810 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
24820 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
24830 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
24840 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24850 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
24860 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
24870 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
24880 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
24890 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
248a0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
248b0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
248c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
248d0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
248e0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
248f0 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
24900 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
24910 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
24920 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
24930 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
24940 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
24950 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
24960 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
24970 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
24980 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
24990 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
249a0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
249b0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
249c0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
249d0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
249e0 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
249f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24a00 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
24a10 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
24a20 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
24a30 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
24a40 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
24a50 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
24a60 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
24a70 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  sg(sqlite3*);.SQ
24a80 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
24a90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
24aa0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
24ab0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
24ac0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24ad0 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
24ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
24af0 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
24b00 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
24b10 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
24b20 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
24b30 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
24b40 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
24b50 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
24b60 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
24b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
24b80 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
24b90 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
24ba0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
24bb0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
24bc0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
24bd0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
24be0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
24bf0 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
24c00 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
24c10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
24c20 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
24c30 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
24c40 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
24c50 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
24c60 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
24c70 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
24c80 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
24c90 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
24ca0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
24cb0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
24cc0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
24cd0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
24ce0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
24cf0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
24d00 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
24d10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24d20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
24d30 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
24d40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
24d50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
24d60 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
24d70 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
24d80 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
24d90 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
24da0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
24db0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
24dc0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
24dd0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
24de0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
24df0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
24e00 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
24e10 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
24e20 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
24e30 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
24e40 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
24e50 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
24e60 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
24e70 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
24e80 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
24e90 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
24ea0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
24eb0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
24ec0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
24ed0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
24ee0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
24ef0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
24f00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
24f10 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
24f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24f30 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
24f40 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
24f50 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
24f60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
24f70 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
24f80 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
24f90 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
24fa0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
24fb0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
24fc0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
24fd0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
24fe0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
24ff0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
25000 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
25010 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
25020 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
25030 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
25040 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
25050 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
25060 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
25070 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
25080 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
25090 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
250a0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
250b0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
250c0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
250d0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
250e0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
250f0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
25100 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
25110 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
25120 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
25130 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
25140 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
25150 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
25160 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
25170 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25180 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
25190 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
251a0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
251b0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
251c0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
251d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
251e0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
251f0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
25200 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
25210 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
25220 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
25230 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
25240 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
25250 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
25260 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
25270 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
25280 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
25290 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
252a0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
252b0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
252c0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
252d0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
252e0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
252f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
25300 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
25310 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
25320 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
25330 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
25340 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
25350 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
25360 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
25370 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
25380 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
25390 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
253a0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
253b0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
253c0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
253d0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
253e0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
253f0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
25400 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
25410 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
25420 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
25430 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
25440 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
25450 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
25460 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
25470 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
25480 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
25490 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
254a0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
254b0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
254c0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
254d0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
254e0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
254f0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
25500 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
25510 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
25520 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
25530 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
25540 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
25550 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
25560 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
25570 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
25580 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
25590 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
255a0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
255b0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
255c0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
255d0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
255e0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
255f0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
25600 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
25610 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
25620 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
25630 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  I int sqlite3_li
25640 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
25650 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
25660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25670 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
25680 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
25690 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
256a0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
256b0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
256c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
256d0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
256e0 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
256f0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
25700 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
25710 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
25720 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
25730 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
25740 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
25750 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
25760 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
25770 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
25780 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
25790 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
257a0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
257b0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
257c0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
257d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
257e0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
257f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
25800 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25810 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
25820 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
25830 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
25840 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
25850 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25860 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
25870 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
25880 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
25890 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
258a0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
258b0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
258c0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
258d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
258e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
258f0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
25900 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
25910 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25920 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25930 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
25940 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
25950 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
25960 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
25970 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
25980 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
25990 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
259a0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
259b0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
259c0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
259d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
259e0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
259f0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
25a00 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
25a10 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25a20 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
25a30 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
25a40 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
25a50 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
25a60 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25a70 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
25a80 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25a90 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
25aa0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
25ab0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25ac0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
25ad0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
25ae0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
25af0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25b00 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
25b10 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
25b20 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
25b30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25b40 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25b50 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
25b60 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
25b70 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
25b80 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
25b90 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
25ba0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
25bb0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
25bc0 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
25bd0 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
25be0 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
25bf0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
25c00 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
25c10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25c20 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
25c30 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
25c40 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
25c50 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
25c60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25c70 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
25c80 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
25c90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25ca0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
25cb0 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
25cc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
25cd0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
25ce0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25cf0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
25d00 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
25d10 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
25d20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25d30 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
25d40 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
25d50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
25d60 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
25d70 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25d80 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
25d90 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
25da0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
25db0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
25dc0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
25dd0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25de0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
25df0 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
25e00 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25e10 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
25e20 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
25e30 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
25e40 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
25e50 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
25e60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
25e70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25e80 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
25e90 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
25ea0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
25eb0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
25ec0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25ed0 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
25ee0 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
25ef0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25f00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
25f10 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
25f20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25f30 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
25f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25f50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25f60 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
25f70 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
25f80 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
25f90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25fa0 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
25fb0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
25fc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25fd0 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
25fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
25ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26000 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
26010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
26020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26030 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
26040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26050 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
26060 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
26070 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
26080 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
26090 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
260a0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
260b0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
260c0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
260d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
260e0 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
260f0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
26100 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
26110 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
26120 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
26130 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
26140 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
26150 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
26160 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
26170 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
26180 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
26190 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
261a0 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
261b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
261c0 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
261d0 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
261e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
261f0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
26200 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
26210 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
26220 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
26230 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
26240 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
26250 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
26260 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
26270 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
26280 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
26290 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
262a0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
262b0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
262c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
262d0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
262e0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
262f0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
26300 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
26310 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
26320 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
26330 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
26340 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
26350 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
26360 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
26370 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
26380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
26390 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
263a0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
263b0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
263c0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
263d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
263e0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
263f0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
26400 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
26410 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
26420 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
26430 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26440 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
26450 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
26460 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26470 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
26480 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
26490 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
264a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
264b0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
264c0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
264d0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
264e0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
264f0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
26500 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
26510 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
26520 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
26530 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
26540 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
26550 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
26560 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
26570 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
26580 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
26590 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
265a0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
265b0 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
265c0 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
265d0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
265e0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
265f0 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
26600 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
26610 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
26620 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
26630 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
26640 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
26650 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
26660 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
26670 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
26680 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
26690 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
266a0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
266b0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
266c0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
266d0 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
266e0 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
266f0 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20  r bytes as this 
26700 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f  saves SQLite fro
26710 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d  m having to.** m
26720 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
26730 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a  e input string..
26740 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
26750 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
26760 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
26770 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
26780 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
26790 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
267a0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
267b0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
267c0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
267d0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
267e0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
267f0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
26800 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
26810 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
26820 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
26830 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
26840 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
26850 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
26860 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
26870 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
26880 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
26890 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
268a0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
268b0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
268c0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
268d0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
268e0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
268f0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
26900 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
26910 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
26920 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
26930 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
26940 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
26950 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
26960 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
26970 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
26980 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
26990 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
269a0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
269b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
269c0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
269d0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
269e0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
269f0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
26a00 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
26a10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26a20 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
26a30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
26a40 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
26a50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
26a60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
26a70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
26a80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26a90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
26aa0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
26ab0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
26ac0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
26ad0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
26ae0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
26af0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
26b00 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
26b10 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
26b20 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
26b30 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
26b40 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
26b50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
26b60 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
26b70 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
26b80 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
26b90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
26ba0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
26bb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
26bc0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
26bd0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
26be0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
26bf0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
26c00 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
26c10 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
26c20 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
26c30 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
26c40 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
26c50 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
26c60 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
26c70 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
26c80 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
26c90 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
26ca0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26cb0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
26cc0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
26cd0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
26ce0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
26cf0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
26d00 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
26d10 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
26d20 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
26d30 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
26d40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
26d50 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
26d60 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
26d70 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
26d80 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
26d90 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
26da0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
26db0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
26dc0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
26dd0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
26de0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
26df0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
26e00 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
26e10 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
26e20 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
26e30 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
26e40 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
26e50 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
26e60 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
26e70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
26e80 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
26e90 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
26ea0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
26eb0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
26ec0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
26ed0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
26ee0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
26ef0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
26f00 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
26f10 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
26f20 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
26f30 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
26f40 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
26f50 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
26f60 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
26f70 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
26f80 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
26f90 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
26fa0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
26fb0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
26fc0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
26fd0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
26fe0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
26ff0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
27000 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
27010 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
27020 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
27030 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
27040 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
27050 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
27060 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27070 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
27080 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
27090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
270a0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
270b0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
270c0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
270d0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
270e0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
270f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
27100 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
27110 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
27120 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
27130 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
27140 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
27150 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
27160 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
27170 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
27180 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
27190 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
271a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
271b0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
271c0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
271d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
271e0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
271f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51  >.** </ol>.*/.SQ
27200 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27210 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
27220 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27230 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27240 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27250 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
27260 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27270 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
27280 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27290 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
272a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
272b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
272c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
272d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
272e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
272f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
27300 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
27310 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
27320 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
27330 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
27340 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
27350 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27360 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
27370 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27380 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27390 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
273a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
273b0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
273c0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
273d0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
273e0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
273f0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27400 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27410 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27420 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27430 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27440 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27450 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27460 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27470 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27480 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27490 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
274a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
274b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
274c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
274d0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
274e0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
274f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
27500 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27510 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
27520 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
27530 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27540 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27550 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
27560 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
27570 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
27580 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27590 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
275a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
275b0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
275c0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
275d0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
275e0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
275f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27600 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27610 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
27620 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
27630 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27640 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27650 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
27660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
27670 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
27680 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
27690 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
276a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
276b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
276c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
276d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
276e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
276f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27700 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
27710 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
27720 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
27730 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
27740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27750 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
27760 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
27770 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
27780 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
27790 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
277a0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
277b0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
277c0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
277d0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
277e0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
277f0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
27800 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
27810 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
27820 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27830 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27840 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  re16_v2()]..*/.S
27850 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
27860 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
27870 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
27880 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
27890 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
278a0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
278b0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
278c0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
278d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
278e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
278f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27900 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
27910 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
27920 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
27930 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
27940 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
27950 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
27960 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
27970 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
27980 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
27990 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
279a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
279b0 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
279c0 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
279d0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
279e0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
279f0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
27a00 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
27a10 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
27a20 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
27a30 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
27a40 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
27a50 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
27a60 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
27a70 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
27a80 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
27a90 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
27aa0 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
27ab0 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
27ac0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
27ad0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
27ae0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
27af0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
27b00 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
27b10 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
27b20 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
27b30 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
27b40 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
27b50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27b60 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
27b70 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27b80 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
27b90 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
27ba0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
27bb0 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
27bc0 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
27bd0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
27be0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
27bf0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
27c00 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
27c10 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
27c20 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
27c30 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
27c40 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
27c50 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
27c60 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
27c70 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
27c80 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
27c90 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
27ca0 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
27cb0 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
27cc0 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
27cd0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
27ce0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
27cf0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
27d00 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
27d10 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27d20 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
27d30 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
27d40 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
27d50 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
27d60 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
27d70 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
27d80 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
27d90 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
27da0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
27db0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
27dc0 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
27dd0 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  disk..*/.SQLITE_
27de0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27df0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
27e00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
27e10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27e20 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
27e30 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
27e40 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
27e50 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
27e60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
27e70 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
27e80 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
27e90 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
27ea0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27eb0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
27ec0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
27ed0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
27ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27ef0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
27f00 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
27f10 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
27f20 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
27f30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
27f40 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
27f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
27f60 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
27f70 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
27f80 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
27f90 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
27fa0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
27fb0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
27fc0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
27fd0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
27fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
27ff0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
28000 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
28010 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
28020 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
28030 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
28040 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
28050 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
28060 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
28070 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
28080 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
28090 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
280a0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
280b0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
280c0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
280d0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
280e0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
280f0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
28100 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
28110 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
28120 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
28130 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
28140 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
28150 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
28160 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
28170 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28180 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28190 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
281a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
281b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
281c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
281d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
281e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
281f0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
28200 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28210 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
28220 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
28230 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
28240 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
28250 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
28260 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
28270 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
28280 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
28290 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
282a0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
282b0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
282c0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
282d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
282e0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
282f0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
28300 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
28310 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
28320 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
28330 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28340 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
28350 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
28360 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
28370 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
28380 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
28390 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
283a0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
283b0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
283c0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
283d0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
283e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
283f0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
28400 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
28410 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
28420 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
28430 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
28440 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
28450 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
28460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28470 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
28480 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
28490 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
284a0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
284b0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
284c0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
284d0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
284e0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
284f0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
28500 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28510 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
28520 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
28530 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
28540 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28550 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
28560 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
28570 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
28580 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
28590 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
285a0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
285b0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
285c0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
285d0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
285e0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
285f0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
28600 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
28610 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
28620 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
28630 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
28640 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
28650 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
28660 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
28670 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
28680 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28690 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
286a0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
286b0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
286c0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
286d0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
286e0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
286f0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
28700 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
28710 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
28720 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
28730 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
28740 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
28750 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28760 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
28770 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
28780 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
28790 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
287a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
287b0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
287c0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
287d0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
287e0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
287f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28800 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
28810 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
28820 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
28830 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
28840 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
28850 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
28860 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
28870 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
28880 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28890 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
288a0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
288b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
288c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
288d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
288e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
288f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
28900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
28910 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
28920 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
28930 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
28940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28950 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
28960 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
28970 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
28980 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
28990 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
289a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
289b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
289c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
289d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
289e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
289f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28a00 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
28a10 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
28a20 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
28a30 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
28a40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
28a50 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
28a60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28a70 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
28a80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28a90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
28aa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
28ab0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
28ac0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
28ad0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
28ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
28af0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
28b00 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
28b10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
28b20 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
28b30 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
28b40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
28b50 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
28b60 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
28b70 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
28b80 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
28b90 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
28ba0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28bb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
28bc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
28bd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28be0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
28bf0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
28c00 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
28c10 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
28c20 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
28c30 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
28c40 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
28c50 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
28c60 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
28c70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
28c80 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
28c90 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
28ca0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
28cb0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
28cc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28cd0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
28ce0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
28cf0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
28d00 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
28d10 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
28d20 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
28d30 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
28d40 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
28d50 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
28d60 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
28d70 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
28d80 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
28d90 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
28da0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
28db0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
28dc0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
28dd0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
28de0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
28df0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
28e00 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
28e10 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
28e20 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
28e30 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
28e40 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
28e50 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
28e60 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
28e70 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
28e80 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
28e90 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
28ea0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
28eb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
28ec0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
28ed0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
28ee0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
28ef0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
28f00 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
28f10 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
28f20 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
28f30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
28f40 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
28f50 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
28f60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
28f70 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
28f80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
28f90 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
28fa0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
28fb0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
28fc0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
28fd0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
28fe0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
28ff0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
29000 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
29010 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
29020 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
29030 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
29040 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
29050 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
29060 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
29070 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
29080 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
29090 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
290a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
290b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
290c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
290d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
290e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
290f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
29100 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
29110 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
29120 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
29130 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
29140 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
29150 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29160 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
29170 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
29180 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
29190 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
291a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
291b0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
291c0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
291d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
291e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
291f0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
29200 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
29210 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
29220 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
29230 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
29240 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
29250 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
29260 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
29270 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
29280 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
29290 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
292a0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
292b0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
292c0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
292d0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
292e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
292f0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
29300 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
29310 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
29320 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
29330 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
29340 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
29350 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
29360 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
29370 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
29380 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29390 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
293a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
293b0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
293c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
293d0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
293e0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
293f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
29400 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
29410 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29420 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
29430 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
29440 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
29450 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
29460 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
29470 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29480 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
29490 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
294a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
294b0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
294c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
294d0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
294e0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
294f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
29500 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
29510 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
29520 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
29530 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
29540 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
29550 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
29560 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
29570 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
29580 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
29590 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
295a0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
295b0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
295c0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
295d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
295e0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
295f0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
29600 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
29610 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
29620 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
29630 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
29640 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
29650 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
29660 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
29670 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
29680 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
29690 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
296a0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
296b0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
296c0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
296d0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
296e0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
296f0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
29700 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
29710 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
29720 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
29730 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
29740 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
29750 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
29760 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
29770 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
29780 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
29790 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
297a0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
297b0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
297c0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
297d0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
297e0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
297f0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
29800 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
29810 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
29820 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
29830 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29840 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
29850 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
29860 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
29870 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
29880 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
29890 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
298a0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
298b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
298c0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
298d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
298e0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
298f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
29900 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
29910 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
29920 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
29930 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
29940 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
29950 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
29960 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
29970 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
29980 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
29990 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
299a0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
299b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
299c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
299d0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
299e0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
299f0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
29a00 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
29a10 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
29a20 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
29a30 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
29a40 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
29a50 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
29a60 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
29a70 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
29a80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29a90 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
29aa0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
29ab0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
29ac0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
29ad0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
29ae0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
29af0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
29b00 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
29b10 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
29b20 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
29b30 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
29b40 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
29b50 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
29b60 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
29b70 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
29b80 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
29b90 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
29ba0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
29bb0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
29bc0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
29bd0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
29be0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
29bf0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
29c00 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
29c10 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
29c20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
29c30 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
29c40 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
29c50 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29c60 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
29c70 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
29c80 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
29c90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29ca0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
29cb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
29cc0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
29cd0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
29ce0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
29cf0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
29d00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29d10 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
29d20 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
29d30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
29d40 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
29d50 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
29d60 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
29d70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29d80 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
29d90 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
29da0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
29db0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
29dc0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
29dd0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
29de0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
29df0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
29e00 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
29e10 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
29e20 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
29e30 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
29e40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29e50 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
29e60 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
29e70 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
29e80 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
29e90 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
29ea0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
29eb0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
29ec0 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
29ed0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
29ee0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
29ef0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
29f00 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
29f10 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
29f20 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
29f30 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
29f40 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
29f50 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
29f60 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
29f70 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
29f80 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
29f90 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
29fa0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
29fb0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
29fc0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
29fd0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29fe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29ff0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a010 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a020 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2a030 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a040 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2a050 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a060 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2a070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a080 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2a090 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2a0a0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2a0b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2a0c0 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ind_blob64(sqlit
2a0d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2a0e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
2a0f0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2a100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a110 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2a120 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2a130 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a140 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2a150 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2a160 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
2a170 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a180 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2a190 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
2a1a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a1b0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2a1c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a1d0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2a1e0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
2a1f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a200 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2a210 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
2a220 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a230 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2a240 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2a250 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2a260 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2a270 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a280 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2a290 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a2a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2a2b0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2a2c0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2a2d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a2e0 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
2a2f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a300 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
2a310 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2a320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a330 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2a340 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
2a350 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53  har encoding);.S
2a360 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a370 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2a380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a390 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2a3a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2a3b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a3c0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2a3d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a3e0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2a3f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2a400 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2a410 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
2a420 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2a430 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2a440 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2a450 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2a460 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2a470 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2a480 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2a490 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2a4a0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2a4b0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2a4c0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2a4d0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2a4e0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2a4f0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2a500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a510 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2a520 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2a530 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2a540 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2a550 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2a560 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2a570 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2a580 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2a590 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2a5a0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2a5b0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2a5c0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2a5d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2a5e0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2a5f0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2a600 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2a610 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2a620 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2a630 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2a640 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a650 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a660 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2a670 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a680 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a690 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2a6a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a6b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2a6c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2a6d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2a6e0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2a6f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2a700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a710 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2a720 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
2a730 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2a740 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2a750 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2a760 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2a770 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2a780 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2a790 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2a7a0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2a7b0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2a7c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2a7d0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2a7e0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2a7f0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2a800 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2a810 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2a820 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2a830 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2a840 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2a850 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2a860 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2a870 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2a880 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2a890 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2a8a0 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2a8b0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2a8c0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2a8d0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2a8e0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2a8f0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2a900 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2a910 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2a920 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2a930 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2a940 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2a950 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2a960 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2a970 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2a980 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2a990 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2a9a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2a9b0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2a9c0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2a9d0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2a9e0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2a9f0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2aa00 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2aa10 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2aa20 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2aa30 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2aa40 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2aa50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2aa60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2aa70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2aa80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2aa90 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2aaa0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2aab0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2aac0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2aad0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2aae0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2aaf0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2ab00 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2ab10 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2ab20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ab30 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2ab40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2ab50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ab60 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2ab70 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2ab80 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
2ab90 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2aba0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2abb0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2abc0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2abd0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2abe0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2abf0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2ac00 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2ac10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2ac20 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2ac30 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2ac40 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2ac50 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2ac60 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2ac70 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2ac80 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2ac90 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2aca0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2acb0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2acc0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2acd0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2ace0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2acf0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2ad00 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2ad10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ad20 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2ad30 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ad40 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ad50 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2ad60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ad70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2ad80 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2ad90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2ada0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2adb0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2adc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2add0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2ade0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2adf0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2ae00 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2ae10 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
2ae20 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
2ae30 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
2ae40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
2ae50 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
2ae60 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2ae70 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
2ae80 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
2ae90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2aea0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
2aeb0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
2aec0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
2aed0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54  o NULL..*/.SQLIT
2aee0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2aef0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2af00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2af10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2af20 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2af30 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2af40 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
2af50 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2af60 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2af70 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2af80 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2af90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2afa0 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2afb0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2afc0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2afd0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2afe0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2aff0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2b000 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2b010 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b020 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2b030 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2b040 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b050 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2b060 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b070 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b080 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2b090 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2b0a0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b0b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b0c0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2b0d0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2b0e0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2b0f0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2b100 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2b110 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2b120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b130 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2b140 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b150 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2b160 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2b170 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2b180 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b190 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2b1a0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2b1b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2b1c0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2b1d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b1e0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2b1f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b200 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2b210 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2b220 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2b230 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2b240 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2b250 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2b260 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2b270 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2b280 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b290 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2b2a0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2b2b0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2b2c0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2b2d0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2b2e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b2f0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2b300 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2b310 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2b320 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2b330 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2b340 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b350 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2b360 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2b370 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2b380 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2b390 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2b3a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b3b0 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2b3c0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2b3d0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2b3e0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2b3f0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2b400 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2b410 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2b420 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2b430 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2b440 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2b450 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2b460 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2b470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2b480 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2b490 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2b4a0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2b4b0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2b4c0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2b4d0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2b4e0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2b4f0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2b500 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2b510 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2b520 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2b530 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2b540 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2b550 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2b560 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  xt..*/.SQLITE_AP
2b570 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2b580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b590 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b5a0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
2b5b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2b5c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b5d0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2b5e0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
2b5f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
2b600 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
2b610 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2b620 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2b630 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2b640 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2b650 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2b660 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2b670 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2b680 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2b690 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2b6a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2b6b0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2b6c0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2b6d0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2b6e0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2b6f0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2b700 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2b710 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2b720 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2b730 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2b740 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2b750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2b760 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2b770 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2b780 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2b790 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2b7a0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2b7b0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2b7c0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2b7d0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2b7e0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2b7f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b800 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2b810 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2b820 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2b830 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2b840 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2b850 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2b860 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2b870 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2b880 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2b890 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2b8a0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2b8b0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2b8c0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2b8d0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2b8e0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2b8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2b900 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2b910 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2b920 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2b930 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2b940 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2b950 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2b960 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2b970 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2b980 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2b990 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2b9a0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2b9b0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2b9c0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2b9d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2b9e0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2b9f0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2ba00 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2ba10 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2ba20 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2ba30 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2ba40 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2ba50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2ba60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2ba70 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2ba80 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2ba90 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2baa0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2bab0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2bac0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2bad0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2bae0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2baf0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2bb00 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2bb10 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2bb20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2bb30 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2bb40 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2bb50 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2bb60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2bb70 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2bb80 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2bb90 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2bba0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2bbb0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2bbc0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2bbd0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2bbe0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2bbf0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2bc00 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2bc10 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2bc20 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2bc30 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2bc40 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2bc50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2bc60 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2bc70 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2bc80 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2bc90 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2bca0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2bcb0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2bcc0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2bcd0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2bce0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2bcf0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2bd00 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2bd10 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2bd20 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2bd30 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2bd40 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2bd50 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2bd60 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2bd70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2bd80 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2bd90 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2bda0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2bdb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2bdc0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2bdd0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2bde0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2bdf0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2be00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2be10 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2be20 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2be30 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2be40 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2be50 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2be60 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2be70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2be80 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
2be90 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2bea0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2beb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2bec0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2bed0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2bee0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2bef0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2bf00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bf10 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2bf20 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2bf30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2bf40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2bf50 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
2bf60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2bf70 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2bf80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bf90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2bfa0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2bfb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2bfc0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2bfd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bfe0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
2bff0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c000 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c010 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
2c020 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
2c030 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
2c040 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2c050 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2c060 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c070 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2c080 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2c090 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2c0a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2c0b0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2c0c0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2c0d0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2c0e0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2c0f0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2c100 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2c110 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2c120 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2c130 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2c140 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2c150 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2c160 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2c170 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2c180 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2c190 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2c1a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2c1b0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2c1c0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2c1d0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2c1e0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2c1f0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2c200 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2c210 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2c220 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2c230 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2c240 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2c250 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2c260 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2c270 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2c280 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2c290 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2c2a0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2c2b0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2c2c0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2c2d0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2c2e0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2c2f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2c300 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2c310 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2c320 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2c330 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2c340 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2c350 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2c360 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2c370 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2c380 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2c390 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2c3a0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2c3b0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2c3c0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2c3d0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2c3e0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2c3f0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2c400 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2c410 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2c420 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2c430 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2c440 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2c450 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2c460 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2c470 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2c480 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2c490 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2c4a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2c4b0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2c4c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c4d0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2c4e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2c4f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2c500 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2c510 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2c520 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2c530 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2c540 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
2c550 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
2c560 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
2c570 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
2c580 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
2c590 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c5a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2c5b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2c5c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
2c5d0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
2c5e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c5f0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2c600 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
2c610 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2c620 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
2c630 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2c640 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
2c650 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
2c660 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
2c670 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2c680 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2c690 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2c6a0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2c6b0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2c6c0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2c6d0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2c6e0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2c6f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c700 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2c710 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2c720 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2c730 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2c740 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2c750 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2c760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2c770 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2c780 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2c790 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2c7a0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2c7b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2c7c0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2c7d0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2c7e0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2c7f0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2c800 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2c810 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2c820 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2c830 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2c840 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2c850 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2c860 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2c870 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2c880 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2c890 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2c8a0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2c8b0 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2c8c0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2c8d0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2c8e0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2c8f0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2c900 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2c910 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2c920 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2c930 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2c940 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2c950 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2c960 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2c970 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2c980 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2c990 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2c9a0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2c9b0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2c9c0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2c9d0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2c9e0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2c9f0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2ca00 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2ca10 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2ca20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
2ca30 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2ca40 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
2ca50 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
2ca60 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
2ca70 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
2ca80 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2ca90 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
2caa0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2cab0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
2cac0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
2cad0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
2cae0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2caf0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2cb00 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
2cb10 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
2cb20 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
2cb30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2cb40 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
2cb50 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
2cb60 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
2cb70 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
2cb80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
2cb90 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
2cba0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
2cbb0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
2cbc0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
2cbd0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
2cbe0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
2cbf0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
2cc00 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
2cc10 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
2cc20 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
2cc30 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
2cc40 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
2cc50 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2cc60 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
2cc70 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
2cc80 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
2cc90 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
2cca0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
2ccb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
2ccc0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
2ccd0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
2cce0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
2ccf0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
2cd00 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
2cd10 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2cd20 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2cd30 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
2cd40 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
2cd50 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
2cd60 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
2cd70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
2cd80 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
2cd90 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2cda0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
2cdb0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
2cdc0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
2cdd0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
2cde0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2cdf0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
2ce00 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
2ce10 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
2ce20 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
2ce30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ce40 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
2ce50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ce60 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
2ce70 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
2ce80 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2ce90 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2cea0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
2ceb0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2cec0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
2ced0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
2cee0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
2cef0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
2cf00 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
2cf10 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
2cf20 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
2cf30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cf40 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
2cf50 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
2cf60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2cf70 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
2cf80 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
2cf90 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
2cfa0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
2cfb0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
2cfc0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
2cfd0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
2cfe0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
2cff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d000 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
2d010 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
2d020 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
2d030 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
2d040 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
2d050 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
2d060 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
2d070 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
2d080 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
2d090 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
2d0a0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
2d0b0 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
2d0c0 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2d0d0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
2d0e0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2d0f0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
2d100 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2d110 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
2d120 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
2d130 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
2d140 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2d150 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
2d160 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d170 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
2d180 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
2d190 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
2d1a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2d1b0 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
2d1c0 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
2d1d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2d1e0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
2d1f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d200 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
2d210 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
2d220 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
2d230 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
2d240 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2d250 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
2d260 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
2d270 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
2d280 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
2d290 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
2d2a0 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
2d2b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
2d2c0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
2d2d0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
2d2e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2d2f0 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
2d300 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
2d310 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
2d320 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
2d330 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
2d340 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
2d350 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
2d360 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
2d370 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2d380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
2d390 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
2d3a0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
2d3b0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
2d3c0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
2d3d0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
2d3e0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
2d3f0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
2d400 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2d410 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
2d420 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d430 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d440 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
2d450 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
2d460 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
2d470 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2d480 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2d490 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2d4a0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2d4b0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2d4c0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2d4d0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2d4e0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2d4f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d500 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2d510 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2d520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2d530 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2d540 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d550 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2d560 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d570 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2d580 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2d590 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2d5a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2d5b0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2d5c0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2d5d0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2d5e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2d5f0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2d600 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2d610 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2d620 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2d630 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2d640 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  mended..*/.SQLIT
2d650 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d660 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2d670 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2d680 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2d690 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2d6a0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2d6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d6c0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2d6d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2d6e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2d6f0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2d700 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2d710 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2d720 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d730 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2d740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d750 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2d760 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2d770 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2d780 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2d790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2d7a0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2d7b0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2d7c0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2d7d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d7e0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2d7f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2d800 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2d810 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2d820 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2d830 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2d840 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2d850 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2d860 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2d870 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2d880 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d890 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2d8a0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2d8b0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2d8c0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2d8d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2d8e0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2d8f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d900 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2d910 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2d920 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2d930 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2d940 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2d950 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2d960 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2d970 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2d980 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2d990 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2d9a0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2d9b0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2d9c0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2d9d0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2d9e0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
2d9f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2da00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2da10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2da20 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2da30 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2da40 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2da50 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2da60 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2da70 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2da80 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2da90 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2daa0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2dab0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2dac0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2dad0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2dae0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2daf0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2db00 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2db10 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2db20 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2db30 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2db40 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2db50 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2db60 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2db70 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2db80 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2db90 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2dba0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2dbb0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2dbc0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2dbd0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2dbe0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2dbf0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2dc00 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2dc10 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2dc20 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2dc30 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2dc40 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2dc50 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2dc60 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2dc70 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2dc80 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2dc90 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2dca0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2dcb0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2dcc0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2dcd0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2dce0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2dcf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2dd00 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2dd10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2dd20 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2dd30 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2dd40 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2dd50 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2dd60 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2dd70 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2dd80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2dd90 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2dda0 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
2ddb0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
2ddc0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2ddd0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2dde0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2ddf0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2de00 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2de10 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2de20 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2de30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2de40 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2de50 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2de60 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2de70 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2de80 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2de90 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2dea0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2deb0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2dec0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2ded0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2dee0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2def0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2df00 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2df10 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2df20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2df30 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2df40 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2df50 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2df60 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2df70 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2df80 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2df90 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2dfa0 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2dfb0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2dfc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2dfd0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2dfe0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2dff0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2e000 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2e010 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2e020 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2e030 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2e040 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2e050 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2e060 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2e070 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2e080 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2e090 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2e0a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2e0b0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2e0c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2e0d0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2e0e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e0f0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2e100 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2e110 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2e120 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2e130 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2e140 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2e150 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2e160 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2e170 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e180 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2e190 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2e1a0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2e1b0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2e1c0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2e1d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2e1e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2e1f0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2e200 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2e210 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2e220 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2e230 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2e240 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2e250 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2e260 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2e270 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2e280 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2e290 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2e2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2e2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2e2c0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2e2d0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2e2e0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2e2f0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2e300 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2e310 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2e320 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2e330 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2e340 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2e350 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2e360 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2e370 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2e380 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2e390 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2e3a0 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2e3b0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2e3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2e3d0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2e3e0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2e3f0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2e400 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2e410 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2e420 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2e430 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2e440 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2e450 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2e460 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2e470 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2e480 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2e490 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2e4a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2e4b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e4c0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2e4d0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2e4e0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2e4f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2e500 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2e510 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2e520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e530 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2e540 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2e550 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e560 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2e570 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2e580 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2e590 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2e5a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e5b0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2e5c0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2e5d0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2e5e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2e5f0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2e600 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e610 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2e620 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2e630 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2e640 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2e650 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2e660 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2e670 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2e680 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2e690 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2e6a0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2e6b0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2e6c0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2e6d0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2e6e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2e6f0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2e700 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e710 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2e720 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2e730 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2e740 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2e750 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2e760 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e770 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2e780 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2e790 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e7a0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2e7b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2e7c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2e7d0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2e7e0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2e7f0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2e800 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2e810 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2e820 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2e830 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2e840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e850 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2e860 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2e870 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2e880 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2e890 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2e8a0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2e8b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e8c0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2e8d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e8e0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2e8f0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e900 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2e910 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2e920 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2e930 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2e940 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2e950 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e960 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e970 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2e980 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2e990 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2e9a0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2e9b0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2e9c0 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2e9d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2e9e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e9f0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2ea00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ea10 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2ea20 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2ea30 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2ea40 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2ea50 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
2ea60 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
2ea70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2ea80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2ea90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2eaa0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2eab0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2eac0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2ead0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
2eae0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
2eaf0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2eb00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2eb10 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
2eb20 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
2eb30 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2eb40 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
2eb50 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2eb60 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2eb70 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
2eb80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2eb90 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
2eba0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2ebb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2ebc0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
2ebd0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
2ebe0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2ebf0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2ec00 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2ec10 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2ec20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ec30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2ec40 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2ec50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ec60 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2ec70 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2ec80 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2ec90 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2eca0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2ecb0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2ecc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2ecd0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2ece0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2ecf0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2ed00 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2ed10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2ed20 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2ed30 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2ed40 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2ed50 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2ed60 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2ed70 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2ed80 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2ed90 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2eda0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2edb0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2edc0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2edd0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2ede0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2edf0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2ee00 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2ee10 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2ee20 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2ee30 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2ee40 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2ee50 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2ee60 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2ee70 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2ee80 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2ee90 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2eea0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2eeb0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2eec0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2eed0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2eee0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2eef0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2ef00 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2ef10 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2ef20 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2ef30 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2ef40 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2ef50 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2ef60 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2ef70 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2ef80 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2ef90 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2efa0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2efb0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2efc0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2efd0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2efe0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2eff0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2f000 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2f010 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2f020 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2f030 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2f040 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2f050 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f060 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2f070 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2f080 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2f090 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2f0a0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2f0b0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2f0c0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2f0d0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2f0e0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2f0f0 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2f100 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2f110 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f120 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
2f130 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
2f140 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2f150 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2f160 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2f170 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2f180 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2f190 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f1a0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
2f1b0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2f1c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
2f1d0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
2f1e0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2f1f0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2f200 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2f210 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2f220 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2f230 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2f240 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2f250 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2f260 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2f270 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2f280 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2f290 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2f2a0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2f2b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2f2c0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2f2d0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2f2e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2f2f0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2f300 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2f310 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2f320 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2f330 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2f340 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2f350 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2f360 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2f370 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2f380 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2f390 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2f3a0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2f3b0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2f3c0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2f3d0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2f3e0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2f3f0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2f400 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2f410 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2f420 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2f430 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2f440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f450 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2f460 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2f470 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2f480 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2f490 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2f4a0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2f4b0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2f4c0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2f4d0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2f4e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2f4f0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2f500 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2f510 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2f520 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2f530 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2f540 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2f550 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f560 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2f570 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2f580 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2f590 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2f5a0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2f5b0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2f5c0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2f5d0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2f5e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2f5f0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2f600 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2f610 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2f620 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2f630 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2f640 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2f650 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2f660 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2f670 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2f680 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2f690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f6a0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2f6b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f6c0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2f6d0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2f6e0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2f6f0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2f700 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2f710 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2f720 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2f730 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2f740 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2f750 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2f760 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2f770 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2f780 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2f790 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2f7a0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2f7b0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2f7c0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2f7d0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2f7e0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2f7f0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2f800 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2f810 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2f820 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2f830 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2f840 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2f850 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2f860 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2f870 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2f880 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2f890 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2f8a0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2f8b0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2f8c0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2f8d0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2f8e0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2f8f0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2f900 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2f910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f920 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2f930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f940 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2f950 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2f960 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2f970 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f980 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2f990 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2f9a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f9b0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2f9c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f9d0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2f9e0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2f9f0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2fa00 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2fa10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2fa20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2fa30 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2fa40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fa50 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2fa60 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2fa70 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2fa80 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2fa90 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2faa0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2fab0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2fac0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2fad0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2fae0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2faf0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2fb00 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2fb10 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2fb20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2fb30 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2fb40 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2fb50 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2fb60 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2fb70 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2fb80 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2fb90 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2fba0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fbb0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2fbc0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2fbd0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2fbe0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2fbf0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2fc00 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2fc10 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2fc20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fc30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2fc40 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2fc50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2fc60 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2fc70 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2fc80 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2fc90 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2fca0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2fcb0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2fcc0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2fcd0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2fce0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2fcf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2fd00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2fd10 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2fd20 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2fd30 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2fd40 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2fd50 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2fd60 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2fd70 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2fd80 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2fd90 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2fda0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2fdb0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2fdc0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2fdd0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2fde0 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2fdf0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2fe00 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2fe10 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2fe20 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2fe30 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2fe40 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2fe50 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2fe60 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
2fe70 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2fe80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2fe90 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2fea0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2feb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2fec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fed0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fee0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2fef0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ff00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ff10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ff20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2ff30 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
2ff40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2ff50 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2ff60 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2ff70 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2ff80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
2ff90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ffa0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2ffb0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
2ffc0 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2ffd0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2ffe0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2fff0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30000 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
30010 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30020 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
30030 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
30040 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
30050 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30060 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
30070 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30080 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
30090 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
300a0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
300b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
300c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
300d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
300e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
300f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30100 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
30110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
30120 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
30130 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
30140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30150 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
30160 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
30170 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
30180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30190 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
301a0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
301b0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
301c0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
301d0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
301e0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
301f0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
30200 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
30210 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
30220 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
30230 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
30240 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30250 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
30260 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
30270 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
30280 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
30290 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
302a0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
302b0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
302c0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
302d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
302e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
302f0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
30300 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
30310 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
30320 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
30330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30340 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
30350 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
30360 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
30370 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
30380 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
30390 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
303a0 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
303b0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
303c0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
303d0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
303e0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
303f0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
30400 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
30410 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
30420 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30430 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
30440 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
30450 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
30460 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
30470 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
30480 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
30490 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
304a0 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
304b0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
304c0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
304d0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
304e0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
304f0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
30500 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30510 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
30520 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
30530 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
30540 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
30550 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
30560 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
30570 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
30580 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
30590 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
305a0 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
305b0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
305c0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  uption..*/.SQLIT
305d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
305e0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
305f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
30600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30610 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
30620 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
30630 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
30640 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
30650 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
30660 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
30670 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30680 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
30690 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
306a0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
306b0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
306c0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
306d0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
306e0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
306f0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
30700 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
30710 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
30720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
30730 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
30740 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
30750 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
30760 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
30770 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
30780 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
30790 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
307a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
307b0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
307c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
307d0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
307e0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
307f0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
30800 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30810 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30820 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
30830 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
30840 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
30850 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
30860 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
30870 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
30880 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
30890 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
308a0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
308b0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
308c0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
308d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
308e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
308f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30900 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30910 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
30920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30930 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
30940 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
30950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
30960 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
30970 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
30980 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
30990 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
309a0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
309b0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
309c0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
309d0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
309e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
309f0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
30a00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30a10 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ] S..*/.SQLITE_A
30a20 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
30a30 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
30a40 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
30a50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
30a60 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
30a70 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
30a80 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
30a90 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
30aa0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
30ab0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
30ac0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
30ad0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
30ae0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
30af0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
30b00 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
30b10 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
30b20 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
30b30 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
30b40 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
30b50 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
30b60 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
30b70 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
30b80 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
30b90 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
30ba0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
30bb0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
30bc0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
30bd0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
30be0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
30bf0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
30c00 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
30c10 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
30c20 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
30c30 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
30c40 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
30c50 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
30c60 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
30c70 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
30c80 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
30c90 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
30ca0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
30cb0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
30cc0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
30cd0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
30ce0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30cf0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
30d00 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
30d10 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
30d20 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
30d30 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
30d40 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
30d50 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
30d60 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
30d70 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30d80 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
30d90 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
30da0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30db0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
30dc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
30dd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30de0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
30df0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
30e00 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
30e10 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
30e20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
30e30 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
30e40 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
30e50 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
30e60 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
30e70 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
30e80 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
30e90 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
30ea0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
30eb0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
30ec0 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
30ed0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
30ee0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
30ef0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
30f00 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
30f10 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
30f20 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
30f30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
30f40 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
30f50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
30f60 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
30f70 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
30f80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
30f90 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
30fa0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
30fb0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
30fc0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
30fd0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
30fe0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
30ff0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
31000 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
31010 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
31020 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
31030 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
31040 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
31050 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
31060 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
31070 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
31080 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
31090 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
310a0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
310b0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
310c0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
310d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
310e0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
310f0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
31100 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
31110 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
31120 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
31130 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
31140 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
31150 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
31160 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
31170 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
31180 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
31190 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
311a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
311b0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
311c0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
311d0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
311e0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
311f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
31200 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
31210 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
31220 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
31230 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
31240 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
31250 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
31260 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31270 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
31280 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
31290 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
312a0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
312b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
312c0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
312d0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
312e0 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
312f0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31300 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
31310 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
31320 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
31330 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
31340 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
31350 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31360 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
31370 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
31380 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
31390 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
313a0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
313b0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
313c0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
313d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
313e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
313f0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
31400 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
31410 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
31420 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
31430 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
31440 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
31450 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
31460 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
31470 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
31480 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
31490 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
314a0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
314b0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
314c0 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
314d0 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
314e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
314f0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
31500 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
31510 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
31520 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
31530 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
31540 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
31550 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
31560 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
31570 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
31580 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
31590 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
315a0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
315b0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
315c0 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
315d0 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
315e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
315f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
31600 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
31610 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31620 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
31630 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
31640 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
31650 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
31660 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
31670 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
31680 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
31690 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
316a0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
316b0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
316c0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
316d0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
316e0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
316f0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
31700 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
31710 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
31720 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
31730 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
31740 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
31750 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
31760 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
31770 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
31780 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
31790 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
317a0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
317b0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
317c0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
317d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
317e0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
317f0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
31800 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
31810 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
31820 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
31830 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
31840 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
31850 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
31860 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
31870 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
31880 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
31890 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
318a0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
318b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
318c0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
318d0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
318e0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
318f0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
31900 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
31910 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
31920 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
31930 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
31940 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
31950 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
31960 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
31970 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
31980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31990 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
319a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
319b0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
319c0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
319d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
319e0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
319f0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
31a00 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
31a10 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
31a20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
31a30 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
31a40 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
31a50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
31a60 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
31a70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31a80 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
31a90 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
31aa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31ab0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31ac0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
31ad0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
31ae0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
31af0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
31b00 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
31b10 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
31b20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
31b30 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
31b40 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
31b50 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
31b60 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
31b70 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
31b80 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
31b90 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
31ba0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
31bb0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
31bc0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
31bd0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
31be0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
31bf0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
31c00 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31c10 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
31c20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
31c30 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
31c40 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
31c50 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
31c60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31c70 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
31c80 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
31c90 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
31ca0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
31cb0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
31cc0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
31cd0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
31ce0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
31cf0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
31d00 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
31d10 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
31d20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
31d30 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
31d40 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
31d50 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
31d60 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
31d70 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
31d80 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
31d90 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
31da0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
31db0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
31dc0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
31dd0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
31de0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
31df0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
31e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31e10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
31e20 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
31e30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31e40 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
31e50 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
31e60 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
31e70 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
31e80 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
31e90 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
31ea0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
31eb0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
31ec0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
31ed0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
31ee0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
31ef0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
31f00 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
31f10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31f20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31f30 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
31f40 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
31f50 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
31f60 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
31f70 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
31f80 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
31f90 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
31fa0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31fb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31fc0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
31fd0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31fe0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31ff0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32000 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
32010 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
32020 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
32030 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32040 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
32050 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
32060 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
32070 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
32080 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
32090 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
320a0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
320b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
320c0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
320d0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
320e0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
320f0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
32100 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
32110 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
32120 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
32130 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
32140 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32150 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
32160 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
32170 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
32180 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
32190 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
321a0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
321b0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
321c0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
321d0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
321e0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
321f0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
32200 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32210 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32220 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
32230 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32240 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
32250 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
32260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32270 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
32280 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
32290 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
322a0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
322b0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
322c0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
322d0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
322e0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
322f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32300 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
32310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32320 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
32330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32340 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
32350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32360 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
32370 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
32380 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
32390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
323a0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
323b0 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
323c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
323d0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
323e0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
323f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32400 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
32410 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
32420 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
32430 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
32440 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
32450 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
32460 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
32470 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
32480 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
32490 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
324a0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
324b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
324c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
324d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
324e0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
324f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32500 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
32510 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
32520 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
32530 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
32540 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
32550 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
32560 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
32570 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
32580 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
32590 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
325a0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
325b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
325c0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
325d0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
325e0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
325f0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
32600 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
32610 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
32620 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
32630 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
32640 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
32650 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
32660 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
32670 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
32680 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
32690 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
326a0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
326b0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
326c0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
326d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
326e0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
326f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32700 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
32710 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
32720 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
32730 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32740 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
32750 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
32760 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
32770 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32780 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
32790 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
327a0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
327b0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
327c0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
327d0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
327e0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
327f0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
32800 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32810 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
32820 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
32830 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
32840 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32850 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
32860 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
32870 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
32880 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
32890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
328a0 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
328b0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
328c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
328d0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
328e0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
328f0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
32900 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
32910 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32920 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
32930 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
32940 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
32950 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
32960 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
32970 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
32980 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
32990 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
329a0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
329b0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
329c0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
329d0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
329e0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
329f0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
32a00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
32a10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
32a20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32a30 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
32a40 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
32a50 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
32a60 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
32a70 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
32a80 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
32a90 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
32aa0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
32ab0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
32ac0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32ad0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
32ae0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
32af0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
32b00 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
32b10 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
32b20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32b30 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
32b40 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
32b50 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
32b60 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
32b70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
32b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
32b90 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
32ba0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
32bb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32bc0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
32bd0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
32be0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
32bf0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
32c00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
32c10 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
32c20 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
32c30 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
32c40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
32c50 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
32c60 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32c70 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
32c80 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
32c90 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
32ca0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
32cb0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
32cc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32cd0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
32ce0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
32cf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
32d00 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
32d10 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
32d20 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
32d30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32d40 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
32d50 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
32d60 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
32d70 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
32d80 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
32d90 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
32da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
32db0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
32dc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
32dd0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
32de0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
32df0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
32e00 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
32e10 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
32e20 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
32e30 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
32e40 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
32e50 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
32e60 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
32e70 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
32e80 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
32e90 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
32ea0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
32eb0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
32ec0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
32ed0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
32ee0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
32ef0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
32f00 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
32f10 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
32f20 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
32f30 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
32f40 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
32f50 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
32f60 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
32f70 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
32f80 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
32f90 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
32fa0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
32fb0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
32fc0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
32fd0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
32fe0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
32ff0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
33000 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
33010 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
33020 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
33030 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
33040 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
33050 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
33060 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
33070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33080 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
33090 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
330a0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
330b0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
330c0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
330d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
330e0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
330f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
33100 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
33110 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
33120 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
33130 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
33140 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33150 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
33160 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
33170 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
33180 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
33190 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
331a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
331b0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
331c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
331d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
331e0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
331f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
33200 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
33210 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
33220 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33230 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33240 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33250 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
33260 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
33270 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
33280 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
33290 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
332a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
332b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
332c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
332d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
332e0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
332f0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
33300 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
33310 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
33320 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
33330 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33340 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33350 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
33360 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33370 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
33380 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
33390 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
333a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
333b0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
333c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
333d0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
333e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
333f0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
33400 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
33410 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
33420 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
33430 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33440 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33450 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
33460 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
33470 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
33480 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
33490 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
334a0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
334b0 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
334c0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
334d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
334e0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
334f0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
33500 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
33510 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
33520 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
33530 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
33540 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33550 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
33560 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
33570 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
33580 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
33590 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
335a0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
335b0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
335c0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
335d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
335e0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
335f0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
33600 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
33610 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
33620 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33630 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
33640 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
33650 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
33660 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
33670 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
33680 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
33690 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
336a0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
336b0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
336c0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
336d0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
336e0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
336f0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
33700 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
33710 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33720 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
33730 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
33740 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
33750 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
33760 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
33770 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
33780 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
33790 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
337a0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
337b0 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
337c0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
337d0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
337e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
337f0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
33800 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
33810 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
33820 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
33830 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
33840 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33850 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
33860 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
33870 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
33880 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
33890 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
338a0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
338b0 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
338c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
338d0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
338e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
338f0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
33900 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
33910 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33920 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
33930 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
33940 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
33950 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
33960 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
33970 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
33980 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
33990 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
339a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
339b0 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
339c0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
339d0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
339e0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
339f0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
33a00 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
33a10 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
33a20 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
33a30 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
33a40 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
33a50 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
33a60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33a70 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
33a80 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
33a90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
33aa0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
33ab0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
33ac0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
33ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
33ae0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
33af0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33b00 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
33b10 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
33b20 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
33b30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
33b40 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
33b50 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
33b60 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
33b70 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
33b80 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
33b90 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
33ba0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
33bb0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
33bc0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
33bd0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
33be0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
33bf0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
33c00 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
33c10 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
33c20 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
33c30 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
33c40 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
33c50 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
33c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
33c70 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
33c80 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
33c90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33ca0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
33cb0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
33cc0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
33cd0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
33ce0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
33cf0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
33d00 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
33d10 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
33d20 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
33d30 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
33d40 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
33d50 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
33d60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33d70 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
33d80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33d90 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
33da0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
33db0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
33dc0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
33dd0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
33de0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
33df0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
33e00 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33e10 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
33e20 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
33e30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33e40 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
33e50 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
33e60 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
33e70 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
33e80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33e90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33ea0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
33eb0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
33ec0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
33ed0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
33ee0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
33ef0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
33f00 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
33f10 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
33f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33f30 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
33f40 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
33f50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33f60 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
33f70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33f80 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33f90 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
33fa0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
33fb0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
33fc0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
33fd0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  function..*/.SQL
33fe0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
33ff0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
34000 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
34010 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
34020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
34030 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
34040 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
34050 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
34060 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
34070 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
34080 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
34090 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
340a0 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
340b0 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
340c0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
340d0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
340e0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
340f0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
34100 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
34110 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
34120 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
34130 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
34140 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
34150 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
34160 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
34170 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
34180 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
34190 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
341a0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
341b0 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
341c0 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
341d0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
341e0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
341f0 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
34200 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
34210 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
34220 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
34230 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
34240 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
34250 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
34260 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
34270 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
34280 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
34290 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
342a0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
342b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
342c0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
342d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
342e0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
342f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
34300 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
34310 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
34320 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
34330 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
34340 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
34350 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
34360 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
34370 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
34380 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34390 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
343a0 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
343b0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
343c0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
343d0 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
343e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
343f0 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
34400 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
34410 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
34420 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
34430 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34440 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
34450 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
34460 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
34470 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
34480 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34490 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
344a0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
344b0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
344c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
344d0 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
344e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
344f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34500 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
34510 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
34520 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
34530 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
34540 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
34550 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
34560 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
34570 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
34580 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
34590 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
345a0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
345b0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
345c0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
345d0 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
345e0 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
345f0 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
34600 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
34610 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
34620 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
34630 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
34640 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
34650 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
34660 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
34670 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
34680 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
34690 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
346a0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
346b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
346c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
346d0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
346e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
346f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
34700 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
34710 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34720 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
34730 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
34740 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
34750 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
34760 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
34770 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34780 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
34790 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
347a0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
347b0 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
347c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
347d0 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
347e0 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
347f0 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
34800 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
34810 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
34820 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
34830 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
34840 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
34850 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
34860 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
34870 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
34880 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34890 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
348a0 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
348b0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
348c0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
348d0 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
348e0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
348f0 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
34900 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
34910 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
34920 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34930 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
34940 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
34950 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
34960 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
34970 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
34980 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
34990 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
349a0 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
349b0 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
349c0 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
349d0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
349e0 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
349f0 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
34a00 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
34a10 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
34a20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34a30 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
34a40 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
34a50 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
34a60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34a70 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
34a80 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34a90 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
34aa0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
34ab0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
34ac0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
34ad0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34ae0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
34af0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
34b00 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
34b10 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
34b20 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
34b30 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
34b40 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
34b50 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
34b60 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
34b70 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
34b80 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
34b90 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
34ba0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
34bb0 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
34bc0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
34bd0 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
34be0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
34bf0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
34c00 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
34c10 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
34c20 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
34c30 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
34c40 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
34c50 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
34c60 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
34c70 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
34c80 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
34c90 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
34ca0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
34cb0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
34cc0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
34cd0 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
34ce0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
34cf0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
34d00 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
34d10 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
34d20 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
34d30 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
34d40 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
34d50 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
34d60 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
34d70 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
34d80 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
34d90 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
34da0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
34db0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
34dc0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
34dd0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
34de0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
34df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
34e00 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
34e10 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
34e20 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
34e30 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
34e40 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
34e50 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
34e60 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
34e70 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
34e80 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
34e90 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
34ea0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
34eb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
34ec0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
34ed0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
34ee0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
34ef0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34f00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34f10 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
34f20 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
34f30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
34f40 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
34f50 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
34f60 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
34f70 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
34f80 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
34f90 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
34fa0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
34fb0 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
34fc0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
34fd0 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
34fe0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
34ff0 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
35000 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
35010 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
35020 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35030 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
35040 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
35050 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
35060 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35070 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
35080 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
35090 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
350a0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
350b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
350c0 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
350d0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
350e0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
350f0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
35100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35110 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
35120 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
35130 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
35140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35150 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35160 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
35170 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
35180 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
35190 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
351a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
351b0 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
351c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
351d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
351e0 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
351f0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35200 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
35210 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
35220 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35230 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
35240 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
35250 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
35260 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
35270 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35280 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
35290 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
352a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
352b0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
352c0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
352d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
352e0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
352f0 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
35300 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
35310 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
35320 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
35330 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
35340 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
35350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35360 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
35370 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
35380 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
35390 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
353a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
353b0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
353c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
353d0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
353e0 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
353f0 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
35400 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
35410 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35420 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
35430 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
35440 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
35450 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
35460 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35470 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
35480 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35490 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
354a0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
354b0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
354c0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
354d0 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
354e0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
354f0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
35500 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
35510 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
35520 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
35530 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
35540 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
35550 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
35560 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
35570 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
35580 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
35590 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
355a0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
355b0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
355c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
355d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
355e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
355f0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
35600 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
35610 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
35620 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
35630 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
35640 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
35650 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
35660 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
35670 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
35680 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
35690 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
356a0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
356b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
356c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
356d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
356e0 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
356f0 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
35700 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
35710 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
35720 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
35730 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
35740 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
35750 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
35760 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
35770 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35780 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
35790 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
357a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
357b0 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
357c0 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
357d0 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
357e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
357f0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
35800 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
35810 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
35820 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
35830 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
35840 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
35850 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
35860 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
35870 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35880 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
35890 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
358a0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
358b0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
358c0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
358d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
358e0 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
358f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35900 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
35910 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
35920 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
35930 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35940 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35950 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
35960 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
35970 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
35980 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
35990 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
359a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
359b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
359c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
359d0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
359e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
359f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
35a00 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
35a10 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
35a20 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
35a30 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
35a40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35a50 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
35a60 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35a70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
35a80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35a90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35aa0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
35ab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35ac0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
35ad0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
35ae0 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
35af0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35b00 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
35b10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35b20 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
35b30 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
35b40 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
35b50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35b60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35b70 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
35b80 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
35b90 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
35ba0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
35bb0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
35bc0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
35bd0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
35be0 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
35bf0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
35c00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35c10 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65  lt_text64() inte
35c20 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35c30 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61  eturn value of a
35c40 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
35c50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35c60 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73  n to be a text s
35c70 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f  tring in an enco
35c80 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65  ding.** specifie
35c90 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28  d by the fifth (
35ca0 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65  and last) parame
35cb0 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20  ter, which must 
35cc0 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51  be one.** of [SQ
35cd0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
35ce0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
35cf0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
35d00 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
35d10 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  ]..** ^SQLite ta
35d20 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
35d30 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
35d40 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
35d50 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
35d60 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
35d70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
35d80 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
35d90 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
35da0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
35db0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
35dc0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
35dd0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
35de0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
35df0 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
35e00 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
35e10 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
35e20 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
35e30 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
35e40 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
35e50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35e60 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35e70 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
35e80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
35e90 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
35ea0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
35eb0 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
35ec0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
35ed0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
35ee0 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
35ef0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35f00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
35f10 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
35f20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
35f30 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
35f40 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
35f50 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
35f60 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
35f70 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
35f80 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
35f90 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
35fa0 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
35fb0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
35fc0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
35fd0 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
35fe0 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
35ff0 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
36000 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
36010 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
36020 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
36030 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
36040 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
36050 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
36060 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
36070 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
36080 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
36090 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
360a0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
360b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
360c0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
360d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
360e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
360f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
36100 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
36110 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
36120 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
36130 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
36140 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
36150 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
36160 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
36170 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
36180 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
36190 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
361a0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
361b0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
361c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
361d0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
361e0 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
361f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36200 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
36210 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
36220 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
36230 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
36240 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
36250 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
36260 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
36270 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
36280 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
36290 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
362a0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
362b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
362c0 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
362d0 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
362e0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
362f0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
36300 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
36310 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
36320 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36330 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
36340 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36350 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
36360 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
36370 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
36380 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
36390 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
363a0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
363b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
363c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
363d0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
363e0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
363f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36400 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
36410 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
36420 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
36430 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36440 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36450 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
36460 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
36470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
36480 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
36490 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
364a0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
364b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
364c0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
364d0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
364e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
364f0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
36500 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36510 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
36520 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
36530 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
36540 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
36550 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
36560 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
36570 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
36580 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
36590 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
365a0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
365b0 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
365c0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
365d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
365e0 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
365f0 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
36600 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
36610 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36620 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
36630 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
36640 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
36650 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
36660 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
36670 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
36680 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
36690 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
366a0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
366b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
366c0 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
366d0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
366e0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
366f0 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
36700 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
36710 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
36720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36730 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
36740 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36750 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
36760 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
36770 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36780 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28  3_result_blob64(
36790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
367a0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 73 71 6c  ,const void*,sql
367b0 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64  ite3_uint64,void
367c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
367d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
367e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
367f0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
36800 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  xt*, double);.SQ
36810 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36830 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
36840 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
36850 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
36860 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
36870 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
36880 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36890 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
368a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
368b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
368c0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
368d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
368e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
368f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36900 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
36910 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
36920 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
36930 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36940 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
36950 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
36960 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
36970 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36980 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
36990 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
369a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
369b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
369c0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
369d0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
369e0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
369f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36a00 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
36a10 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
36a20 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
36a30 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
36a40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36a50 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
36a60 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
36a70 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
36a80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36a90 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ult_text64(sqlit
36aa0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36ab0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
36ac0 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
36ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36ae0 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
36af0 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
36b00 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c  r encoding);.SQL
36b10 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
36b20 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36b30 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36b40 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36b50 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36b60 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
36b70 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
36b80 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
36b90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36ba0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
36bb0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
36bc0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
36bd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36be0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
36bf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36c00 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
36c10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
36c20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36c30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
36c40 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
36c50 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
36c60 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36c70 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
36c80 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
36c90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36ca0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
36cb0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
36cc0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
36cd0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
36ce0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
36cf0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
36d00 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
36d10 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
36d20 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
36d30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36d40 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
36d50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
36d60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
36d70 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
36d80 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
36d90 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
36da0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36db0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
36dc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36dd0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
36de0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
36df0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
36e00 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
36e10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36e20 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
36e30 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
36e40 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
36e50 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
36e60 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
36e70 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
36e80 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
36e90 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
36ea0 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
36eb0 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
36ec0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
36ed0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
36ee0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
36ef0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
36f00 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36f10 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
36f20 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
36f30 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36f40 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
36f50 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
36f60 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
36f70 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
36f80 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
36f90 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
36fa0 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
36fb0 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
36fc0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
36fd0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
36fe0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
36ff0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
37000 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
37010 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
37020 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
37030 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
37040 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
37050 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
37060 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
37070 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
37080 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
37090 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
370a0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
370b0 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
370c0 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
370d0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
370e0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
370f0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
37100 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
37110 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
37120 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
37130 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
37140 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
37150 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
37160 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
37170 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
37180 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
37190 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
371a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
371b0 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
371c0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
371d0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
371e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
371f0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
37200 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
37210 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
37220 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
37230 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
37240 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
37250 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
37260 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
37270 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
37280 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
37290 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
372a0 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
372b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
372c0 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
372d0 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
372e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
372f0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
37300 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
37310 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
37320 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
37330 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
37340 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37350 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
37360 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
37370 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
37380 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
37390 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
373a0 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
373b0 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
373c0 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
373d0 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
373e0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
373f0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37400 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
37410 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
37420 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
37430 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
37440 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
37450 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
37460 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
37470 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
37480 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
37490 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
374a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
374b0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
374c0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
374d0 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
374e0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
374f0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
37500 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37510 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
37520 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
37530 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
37540 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
37550 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
37560 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
37570 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
37580 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
37590 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
375a0 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
375b0 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
375c0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
375d0 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
375e0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
375f0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
37600 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
37610 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
37620 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
37630 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
37640 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
37650 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
37660 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
37670 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
37680 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
37690 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
376a0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
376b0 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
376c0 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
376d0 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
376e0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
376f0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
37700 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
37710 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
37720 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
37730 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
37740 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
37750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37760 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37770 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
37780 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
37790 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
377a0 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
377b0 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
377c0 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
377d0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
377e0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
377f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37800 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
37810 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
37820 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
37830 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
37840 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
37850 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
37860 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
37870 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
37880 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
37890 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
378a0 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
378b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
378c0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
378d0 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
378e0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
378f0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
37900 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
37910 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37920 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
37930 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
37940 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
37950 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37960 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
37970 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
37980 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
37990 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
379a0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
379b0 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
379c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
379d0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
379e0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
379f0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
37a00 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
37a10 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
37a20 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
37a30 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
37a40 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
37a50 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
37a60 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
37a70 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
37a80 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
37a90 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
37aa0 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
37ab0 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
37ac0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
37ad0 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
37ae0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37af0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
37b00 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37b10 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  16()]..*/.SQLITE
37b20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
37b30 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37b40 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
37b50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
37b60 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
37b70 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
37b80 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
37b90 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
37ba0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
37bb0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
37bc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37bd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37be0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
37bf0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37c00 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
37c10 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
37c20 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
37c30 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37c40 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37c50 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37c60 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
37c70 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
37c80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
37c90 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37ca0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
37cb0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
37cc0 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
37cd0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
37ce0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
37cf0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
37d00 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37d10 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37d20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
37d30 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
37d40 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
37d50 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
37d60 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
37d70 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
37d80 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
37d90 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
37da0 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
37db0 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
37dc0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
37dd0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
37de0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
37df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37e00 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
37e10 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
37e20 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
37e30 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
37e40 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
37e50 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
37e60 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
37e70 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
37e80 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37e90 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
37ea0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
37eb0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
37ec0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
37ed0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
37ee0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
37ef0 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
37f00 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37f10 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
37f20 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
37f30 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
37f40 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
37f50 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37f60 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
37f70 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
37f80 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
37f90 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
37fa0 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
37fb0 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
37fc0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
37fd0 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
37fe0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
37ff0 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
38000 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
38010 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
38020 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38030 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
38040 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
38050 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
38060 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
38070 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
38080 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
38090 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
380a0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
380b0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
380c0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
380d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
380e0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
380f0 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
38100 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
38110 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
38120 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
38130 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
38140 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
38150 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
38160 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
38170 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
38180 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
38190 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
381a0 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
381b0 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
381c0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [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 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
381f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38200 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
38210 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38220 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
38230 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
38240 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
38250 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
38260 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
38270 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
38280 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
38290 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
382a0 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  har*).);.SQLITE_
382b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
382c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
382d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
382e0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
382f0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
38300 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
38310 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
38320 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48  .#ifdef SQLITE_H
38330 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
38340 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
38350 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
38360 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
38370 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
38380 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
38390 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
383a0 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
383b0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
383c0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
383d0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
383e0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
383f0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
38400 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
38410 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
38420 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
38430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38440 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
38450 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
38460 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
38470 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
38480 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
38490 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
384a0 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a  sqlite3_key_v2(.
384b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
384c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
384d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
384e0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
384f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
38500 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
38510 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
38520 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
38530 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
38540 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
38550 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
38560 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
38570 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
38580 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
38590 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
385a0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
385b0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
385c0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
385d0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
385e0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
385f0 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
38600 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
38610 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
38620 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
38630 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
38640 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
38650 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
38660 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
38670 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b   int sqlite3_rek
38680 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
38690 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
386a0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
386b0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
386c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
386d0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
386e0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
386f0 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  y */.);.SQLITE_A
38700 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
38710 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  ekey_v2(.  sqlit
38720 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
38730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
38740 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
38750 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
38760 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
38770 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
38780 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
38790 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
387a0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
387b0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6