/ Hex Artifact Content
Login

Artifact 1581bfade051f90dcd28b44c6b04fbf326bec4db:


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 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 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 20 20 20 20 20                  
40b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63a0: 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43  _OPEN_FILEPROTEC
63b0: 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20  TION_MASK       
63c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30            0x0070
63e0: 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65  0000../* Reserve
63f0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
6400: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
6410: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
6420: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
6430: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
6440: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6450: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6460: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6470: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6480: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6490: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
64a0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
64b0: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
64c0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
64d0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
64e0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
64f0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
6500: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
6510: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6520: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6530: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6540: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6570: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6580: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6590: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
65a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
65b0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
65c0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
65d0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
65e0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
65f0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6600: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6610: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6620: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6630: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6640: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6650: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6660: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6670: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6680: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6690: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
66a0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
66b0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
66c0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
66d0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
66e0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
66f0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6700: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6710: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6720: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6730: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6740: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6750: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6760: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6770: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6780: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6790: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
67a0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
67b0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
67c0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
67d0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
67e0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
67f0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6800: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6810: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6820: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6830: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6840: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6850: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6860: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6870: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6880: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6890: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
68a0: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
68c0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
68d0: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
68e0: 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20  ate that a file 
68f0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6900: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6910: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6920: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6930: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6940: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6950: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6960: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6970: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6980: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6990: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
69a0: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  leges..*/.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
6ab0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6b10: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6b20: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b90: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6bb0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
6bc0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c00: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6c20: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6c30: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c50: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6c60: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
6c70: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
6c80: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
6c90: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  BLE             
6ca0: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a   0x00002000../*.
6cb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
6cc0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
6cd0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
6ce0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
6cf0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d00: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
6d10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
6d20: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
6d30: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
6d40: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
6d50: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
6d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6d70: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
6d80: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
6d90: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
6da0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6db0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
6dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6dd0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
6de0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6df0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6e00: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6e10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6e20: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
6e30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
6e40: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
6e50: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
6e60: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6e70: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6e80: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6e90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6ea0: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6eb0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6ec0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6ed0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6ee0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6ef0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6f00: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6f10: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6f20: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
6f30: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
6f40: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
6f50: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
6f60: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6f70: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6f80: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6f90: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6fa0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6fb0: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6fc0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6fd0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6fe0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6ff0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
7000: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
7010: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7020: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
7030: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
7040: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
7050: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
7060: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
7070: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
7080: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
7090: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
70a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
70b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
70c0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
70d0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
70e0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
70f0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
7100: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
7110: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
7120: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
7130: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
7140: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7150: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7160: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7170: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7180: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7190: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
71a0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
71b0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
71c0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
71d0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
71e0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
71f0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
7200: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
7210: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
7220: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
7230: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
7240: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7250: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7260: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7270: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7280: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7290: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
72a0: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
72b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
72c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
72d0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
72e0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
72f0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
7300: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
7310: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
7320: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
7330: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
7340: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7350: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7360: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7380: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7390: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
73a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
73b0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
73c0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
73d0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
73e0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
73f0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
7400: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7410: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
7420: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
7430: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
7440: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7450: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7460: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7470: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7480: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7490: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
74a0: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
74b0: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
74c0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
74d0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
74e0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
74f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
7500: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7510: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7520: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
7530: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
7540: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7550: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7560: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7570: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7580: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7590: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
75a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
75b0: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
75c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
75d0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
75e0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
75f0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
7600: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7610: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
7620: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
7630: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
7640: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7650: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7660: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7670: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7680: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7690: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
76a0: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
76b0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
76c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
76d0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
76e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
76f0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
7700: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
7710: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7720: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
7730: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
7740: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7750: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7760: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7770: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7780: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7790: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
77a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
77b0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
77d0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
77e0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
77f0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
7800: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
7810: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
7820: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
7830: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
7840: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7850: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7860: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7870: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7880: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7890: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
78a0: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
78b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
78c0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
78d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
78e0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
78f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7900: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
7910: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
7920: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7930: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
7940: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
7950: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
7960: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
7970: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
7980: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
7990: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
79a0: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
79b0: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
79c0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
79d0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
79e0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
79f0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
7a00: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
7a10: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
7a20: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
7a30: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
7a40: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
7a50: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
7a60: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
7a70: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
7a80: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
7a90: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
7aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7ab0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
7ac0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7ad0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
7ae0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
7af0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
7b00: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
7b10: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
7b20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7b30: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
7b40: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
7b50: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
7b60: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
7b70: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
7b80: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
7b90: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
7ba0: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
7bb0: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
7bc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
7bd0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
7be0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
7bf0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
7c00: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
7c10: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
7c20: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
7c30: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
7c40: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
7c50: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
7c60: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
7c70: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
7c80: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
7c90: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
7ca0: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
7cb0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
7cc0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
7cd0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7ce0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
7cf0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
7d00: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
7d10: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
7d20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
7d30: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
7d40: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
7d50: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
7d60: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
7d70: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
7d80: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
7d90: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
7da0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
7db0: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
7dc0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
7dd0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
7de0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
7df0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
7e00: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
7e10: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
7e20: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
7e30: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
7e40: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
7e50: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
7e60: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
7e70: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
7e80: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7e90: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7ea0: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7eb0: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7ec0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7ed0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
7ee0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
7ef0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
7f00: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
7f10: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
7f20: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
7f30: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
7f40: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
7f50: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7f60: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f70: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f80: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f90: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7fa0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7fb0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7fc0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7fd0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7fe0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7ff0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
8000: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
8010: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
8020: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8030: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8040: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8050: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8070: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8080: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8090: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
80a0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
80b0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
80c0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
80d0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
80e0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
80f0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8100: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8110: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8120: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8130: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8140: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8150: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8160: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8170: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8180: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8190: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
81a0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
81b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81c0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
81d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
81e0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
81f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8200: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8210: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8220: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8230: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8240: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8250: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8260: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8270: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8280: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8290: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
82a0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
82b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
82d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
82f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8300: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8310: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8320: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8330: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8340: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8350: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8360: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8380: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8390: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
83a0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
83b0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
83c0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
83d0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
83e0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
83f0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8400: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8410: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8420: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8430: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8440: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8450: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8460: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8470: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8480: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8490: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
84a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
84b0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
84c0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
84d0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
84e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
84f0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8500: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8510: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8520: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8530: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8540: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8550: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8560: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8580: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8590: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
85a0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
85b0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
85c0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
85d0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
85e0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
85f0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8600: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8610: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8620: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8630: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8640: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8650: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8660: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8670: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8680: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8690: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
86a0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
86b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
86c0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
86d0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
86e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
86f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8700: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8710: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8720: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8730: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8740: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8750: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8760: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8770: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8780: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8790: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
87a0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
87b0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
87c0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
87d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
87e0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
87f0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8800: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8810: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8820: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8830: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8840: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8850: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8860: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8870: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8880: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8890: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
88a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
88b0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
88d0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
88e0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
88f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8900: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8910: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8920: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8930: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8940: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8950: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8960: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8980: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8990: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
89a0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
89b0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
89c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
89d0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
89e0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
89f0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8a00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8a10: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8a20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a30: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8a40: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8a50: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8a60: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a70: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8aa0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8ab0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8ac0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8ad0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8ae0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8af0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8b00: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8b10: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8b20: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8b30: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8b40: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8b50: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8b60: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b70: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b80: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b90: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
8ba0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8bb0: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8bc0: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8bd0: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8be0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8bf0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8c00: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8c10: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8c20: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8c30: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
8c40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8c50: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
8c60: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
8c70: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
8c80: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
8c90: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8ca0: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
8cb0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
8cc0: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
8cd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
8ce0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
8cf0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
8d00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
8d10: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
8d20: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
8d30: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
8d40: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
8d50: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
8d60: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
8d70: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
8d80: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
8d90: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8da0: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8db0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
8dc0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
8dd0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8de0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c  is defined..** <
8df0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
8e00: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8e10: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
8e20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8e30: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
8e40: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
8e50: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
8e60: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
8e70: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
8e80: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
8e90: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
8ea0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
8eb0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
8ec0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
8ed0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
8ee0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
8ef0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
8f00: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
8f10: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
8f20: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
8f30: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
8f40: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
8f50: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
8f60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
8f70: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
8f80: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8f90: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
8fa0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8fb0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8fc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8fd0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8fe0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
8ff0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9000: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9010: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9020: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9030: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9040: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9050: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9060: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9070: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9080: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9090: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
90a0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
90b0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
90c0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
90d0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
90e0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
90f0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9100: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9110: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9120: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9130: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9140: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9150: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9160: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9170: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9180: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9190: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
91a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
91b0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
91c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
91d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
91e0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
91f0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9200: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9210: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9220: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9230: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9240: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9250: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9260: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  e the [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64  ile_control()] d
9280: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
9290: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
92a0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
92b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
92c0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
92d0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
92e0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
92f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9300: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9320: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9330: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9340: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
9350: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
9360: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
9370: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
9380: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
9390: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
93a0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
93b0: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
93c0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
93d0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
93e0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
93f0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9400: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9410: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9420: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9430: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9440: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
9450: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
9460: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
9470: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
9480: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
9490: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
94a0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
94b0: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
94c0: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
94d0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
94e0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
94f0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9500: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9510: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9520: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9530: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9540: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
9550: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
9560: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
9570: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
9580: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
9590: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
95a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
95c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
95d0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
95e0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
95f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9600: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9610: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9620: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9630: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9640: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9650: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9660: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9670: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9680: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9690: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
96a0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
96b0: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
96c0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
96d0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
96e0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
96f0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9700: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9710: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9720: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9730: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9740: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
9750: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
9760: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9770: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
9780: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9790: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
97a0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
97b0: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
97c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
97d0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
97e0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
97f0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9800: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9810: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9820: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9830: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9840: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9850: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9860: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9870: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9880: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9890: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
98a0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
98b0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
98c0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
98d0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
98e0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
98f0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9900: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9910: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9920: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9930: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9940: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9950: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9960: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9970: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9980: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9990: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
99a0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
99b0: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
99c0: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
99d0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
99e0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
99f0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9a00: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9a10: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9a20: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9a30: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9a40: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9a50: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9a60: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9a70: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9a80: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9a90: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9aa0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9ab0: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9ac0: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9ad0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9ae0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9af0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9b00: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9b10: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9b20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9b30: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9b40: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9b50: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9b60: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9b70: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9b80: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9b90: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9ba0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9bb0: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9bc0: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9bd0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9be0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9bf0: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9c00: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9c10: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9c20: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9c30: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9c40: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
9c50: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
9c60: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9c70: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9c80: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9c90: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9ca0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9cb0: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9cc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9cd0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9ce0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9cf0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9d00: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9d10: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9d20: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9d30: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9d40: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
9d50: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
9d60: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9d70: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9d80: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9d90: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9da0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
9db0: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
9dc0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
9dd0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
9de0: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
9df0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9e00: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
9e10: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
9e20: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
9e30: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
9e40: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
9e50: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
9e60: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
9e70: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
9e80: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
9e90: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
9ea0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
9eb0: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
9ec0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
9ed0: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
9ee0: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
9ef0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
9f00: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
9f10: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
9f20: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
9f30: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
9f40: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9f50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9f60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9f70: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9f80: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9f90: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9fa0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
9fb0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
9fc0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9fd0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9fe0: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
9ff0: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a000: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a010: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a020: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a030: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a040: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a050: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a070: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a080: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a090: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a0a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a0b0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a0c0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a0d0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a0e0: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a0f0: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a100: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a110: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a120: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a130: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a140: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a150: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a160: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a170: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a180: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a190: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a1a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a1b0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a1c0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a1d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a1e0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a1f0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a200: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a210: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a220: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a230: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a240: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a250: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a260: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a270: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a280: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a290: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a2a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a2b0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a2c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2d0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a2e0: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a2f0: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a300: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a310: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a320: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a330: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a340: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a350: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a360: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a370: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a380: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a390: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a3a0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a3b0: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a3c0: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a3d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a3e0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a3f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a400: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a410: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a420: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a430: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a440: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a450: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a460: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a470: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a480: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a490: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a4a0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a4b0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a4c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a4d0: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a4e0: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a4f0: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a500: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a510: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a520: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a530: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a540: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a550: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a560: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a570: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a580: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a590: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a5a0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a5b0: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a5c0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a5d0: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a5e0: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a5f0: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a600: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a610: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a620: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a630: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a640: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
a650: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
a660: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
a670: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
a680: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
a690: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
a6a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a6b0: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
a6c0: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
a6d0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
a6e0: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
a6f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a700: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
a710: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
a720: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
a730: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
a740: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
a750: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a760: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
a770: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a780: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
a790: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
a7a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a7b0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a7c0: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
a7d0: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
a7e0: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
a7f0: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
a800: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
a810: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
a820: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
a830: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
a840: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
a850: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
a860: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
a870: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
a880: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
a890: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
a8a0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
a8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a8c0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a8d0: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
a8e0: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
a8f0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
a900: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
a910: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
a920: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
a930: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
a940: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
a950: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
a960: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
a970: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
a980: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
a990: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
a9a0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
a9b0: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
a9c0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
a9d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a9e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a9f0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
aa00: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
aa10: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
aa20: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
aa30: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
aa40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aa50: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
aa60: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
aa70: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
aa80: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
aa90: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
aaa0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
aab0: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
aac0: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
aad0: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
aae0: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
aaf0: 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ement.  ^If the 
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab10: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab20: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab30: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ab40: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ab50: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ab60: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ab70: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
ab80: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
ab90: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
aba0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
abb0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
abc0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
abd0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
abe0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
abf0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac20: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac30: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
ac40: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
ac50: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
ac60: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
ac70: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ac80: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
ac90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
aca0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
acb0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
acc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
acd0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ace0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
acf0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad00: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad10: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad20: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad30: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ad40: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ad50: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ad60: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ad70: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ad80: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ad90: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ada0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
adb0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
adc0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
add0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ade0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
adf0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae00: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae10: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae20: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae30: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ae40: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
ae50: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
ae60: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
ae70: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
ae80: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
ae90: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
aea0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
aeb0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
aec0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aed0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
aee0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
aef0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af00: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af10: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af20: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af30: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
af40: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
af50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
af60: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
af70: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
af80: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
af90: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
afa0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
afb0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
afc0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
afd0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
afe0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aff0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b000: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b010: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b020: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b030: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b040: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b050: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b060: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b070: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b080: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b090: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b0a0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b0b0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b0c0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b0d0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b0e0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b0f0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b100: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b110: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b120: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b130: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b140: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b150: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b160: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b170: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b180: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b190: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b1a0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b1b0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b1c0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b1d0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b1e0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b1f0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b200: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b210: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b220: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b230: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b240: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b250: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b260: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b270: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b280: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b290: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b2a0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b2b0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b2c0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b2d0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b2e0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b2f0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b300: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b310: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b320: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b330: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b340: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b350: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b360: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b370: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b380: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b390: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b3a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b3c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b3d0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b3e0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b3f0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b400: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b410: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b420: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b430: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b440: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b450: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b460: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b470: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b480: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b490: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b4a0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b4b0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b4c0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b4d0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b4e0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b4f0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b500: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b510: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b520: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b530: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b540: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b550: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b570: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b590: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b5a0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b5b0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b5c0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b5d0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b5e0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b5f0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b600: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b610: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b620: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b630: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b640: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b650: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b660: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b670: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b690: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b6a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b6b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b6c0: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
b6d0: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
b6e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b6f0: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
b700: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
b710: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b720: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
b730: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b740: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b750: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b760: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b770: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b780: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b790: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b7a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b7b0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b7c0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
b7d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b7e0: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
b7f0: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
b800: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b810: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
b820: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
b830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
b840: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
b850: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
b860: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
b870: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
b880: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
b890: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
b8a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b8b0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
b8c0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
b8d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
b8e0: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
b8f0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
b900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b910: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b920: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b930: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
b940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b950: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b960: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
b970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b980: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
b990: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
b9a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b9b0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
b9c0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
b9d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b9e0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
b9f0: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
ba00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba10: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
ba20: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
ba30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ba40: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
ba50: 20 20 20 20 20 20 20 20 32 32 0a 2f 2a 20 64 65          22./* de
ba60: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
ba70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ba80: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
ba90: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
baa0: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
bab0: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
bac0: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
bad0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
bae0: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
baf0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
bb00: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
bb10: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
bb20: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
bb30: 41 53 54 5f 45 52 52 4e 4f 0a 0a 2f 2a 0a 2a 2a  AST_ERRNO../*.**
bb40: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
bb50: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
bb60: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
bb70: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
bb80: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
bb90: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
bba0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
bbb0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
bbc0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
bbd0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
bbe0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
bbf0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
bc00: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
bc10: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
bc20: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
bc30: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
bc40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
bc50: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
bc60: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
bc70: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
bc80: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
bc90: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
bca0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
bcb0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
bcc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bcd0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
bce0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
bcf0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
bd00: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
bd10: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
bd20: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
bd30: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
bd40: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
bd50: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
bd60: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
bd70: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
bd80: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
bd90: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
bda0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
bdb0: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
bdc0: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
bdd0: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
bde0: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
bdf0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
be00: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
be10: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
be20: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
be30: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
be40: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
be50: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
be60: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
be70: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
be80: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
be90: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
bea0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
beb0: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
bec0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
bed0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
bee0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
bef0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
bf00: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
bf10: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
bf20: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
bf30: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
bf40: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
bf50: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
bf60: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
bf70: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
bf80: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
bf90: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
bfa0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
bfb0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
bfc0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
bfd0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
bfe0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
bff0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
c000: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
c010: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
c020: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
c030: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
c040: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
c050: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c060: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c070: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
c080: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
c090: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
c0a0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
c0b0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
c0c0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
c0d0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
c0e0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
c0f0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
c100: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
c110: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
c120: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
c130: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
c140: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
c150: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
c160: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
c170: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
c180: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
c190: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
c1a0: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
c1b0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
c1c0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
c1d0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
c1e0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
c1f0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
c200: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
c210: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
c220: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
c230: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
c240: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
c250: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
c260: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c270: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
c280: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
c290: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
c2a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
c2b0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
c2c0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
c2d0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
c2e0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
c2f0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
c300: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
c310: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
c320: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
c330: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
c340: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
c350: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c360: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
c370: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
c380: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
c390: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
c3a0: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
c3b0: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
c3c0: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
c3d0: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
c3e0: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
c3f0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
c400: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
c410: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
c420: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
c430: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
c440: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
c450: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
c460: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
c470: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
c480: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
c490: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
c4a0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
c4b0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
c4c0: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
c4d0: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
c4e0: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
c4f0: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
c500: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
c510: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
c520: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
c530: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
c540: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
c550: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
c560: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
c570: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
c580: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c590: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
c5a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
c5b0: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
c5c0: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
c5d0: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
c5e0: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
c5f0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
c600: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
c610: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
c620: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
c630: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
c640: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
c650: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
c660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c670: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
c680: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
c690: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
c6a0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
c6b0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
c6c0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
c6d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
c6e0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
c6f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
c700: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
c710: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
c720: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
c730: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
c740: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c750: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
c760: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
c770: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
c780: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
c790: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
c7a0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
c7b0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
c7c0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
c7d0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
c7e0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
c7f0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
c800: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
c810: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
c820: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
c830: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
c840: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
c850: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
c860: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
c870: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
c880: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c890: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
c8a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c8b0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
c8c0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c8d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
c8e0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c8f0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
c900: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c910: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
c920: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
c930: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
c940: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c950: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c960: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
c970: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c980: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
c990: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
c9a0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
c9b0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
c9c0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
c9d0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
c9e0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
c9f0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
ca00: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
ca10: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
ca20: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
ca30: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
ca40: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
ca50: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
ca60: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
ca70: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
ca80: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
ca90: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
caa0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
cab0: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
cac0: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
cad0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
cae0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
caf0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
cb00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
cb10: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
cb20: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
cb30: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
cb40: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
cb50: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
cb60: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
cb70: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
cb80: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
cb90: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
cba0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
cbb0: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
cbc0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
cbd0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
cbe0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
cbf0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
cc00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
cc10: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
cc20: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
cc30: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
cc40: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
cc50: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
cc60: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cc70: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
cc80: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
cc90: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
cca0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
ccb0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
ccc0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
ccd0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
cce0: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
ccf0: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
cd00: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
cd10: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
cd20: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
cd30: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
cd40: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
cd50: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
cd60: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
cd70: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
cd80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
cd90: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
cda0: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
cdb0: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
cdc0: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
cdd0: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
cde0: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
cdf0: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
ce00: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
ce10: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
ce20: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
ce30: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
ce40: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
ce50: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
ce60: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
ce70: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
ce80: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
ce90: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
cea0: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
ceb0: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
cec0: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
ced0: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
cee0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
cef0: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
cf00: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
cf10: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
cf20: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
cf30: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
cf40: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
cf50: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
cf60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
cf70: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
cf80: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
cf90: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
cfa0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
cfb0: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
cfc0: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
cfd0: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
cfe0: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
cff0: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
d000: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
d010: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
d020: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d030: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
d040: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
d050: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d060: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
d070: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
d080: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
d090: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
d0a0: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
d0b0: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
d0c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
d0d0: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
d0e0: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
d0f0: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
d100: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
d110: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
d120: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
d130: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
d140: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d150: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
d160: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
d170: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
d180: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
d190: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
d1a0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
d1b0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
d1c0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
d1d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d1e0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
d1f0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d200: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
d210: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
d220: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
d230: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
d240: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
d250: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
d260: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
d270: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
d280: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
d290: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
d2a0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
d2b0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
d2c0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
d2d0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
d2e0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
d2f0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
d300: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d310: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
d320: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
d330: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
d340: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
d350: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
d360: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
d370: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
d380: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
d390: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
d3a0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
d3b0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
d3c0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
d3d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
d3e0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
d3f0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
d400: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
d410: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
d420: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
d430: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
d440: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
d450: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
d460: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
d470: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
d480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
d490: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
d4a0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
d4b0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
d4c0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
d4d0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
d4e0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
d4f0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
d500: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
d510: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
d520: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
d530: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
d540: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
d550: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
d560: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
d570: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
d580: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
d590: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
d5a0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
d5b0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
d5c0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
d5d0: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
d5e0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
d5f0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
d600: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
d610: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
d620: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
d630: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
d640: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
d650: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
d660: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
d670: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
d680: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
d690: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
d6a0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d6b0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
d6c0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
d6d0: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
d6e0: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
d6f0: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
d700: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
d710: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
d720: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
d730: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
d740: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
d750: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d760: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
d770: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
d780: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
d790: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
d7a0: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
d7b0: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
d7c0: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
d7d0: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
d7e0: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
d7f0: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
d800: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
d810: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
d820: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
d830: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
d840: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
d850: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
d860: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
d870: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
d880: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
d890: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
d8a0: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
d8b0: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
d8c0: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
d8d0: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
d8e0: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
d8f0: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
d900: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
d910: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
d920: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
d930: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
d940: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
d950: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
d960: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
d970: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
d980: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
d990: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
d9a0: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
d9b0: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
d9c0: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
d9d0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
d9e0: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
d9f0: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
da00: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
da10: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
da20: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
da30: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
da40: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
da50: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
da60: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
da70: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
da80: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
da90: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
daa0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
dab0: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
dac0: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
dad0: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
dae0: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
daf0: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
db00: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
db10: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
db20: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
db30: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
db40: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
db50: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
db60: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
db70: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
db80: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
db90: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
dba0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
dbb0: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
dbc0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
dbd0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
dbe0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
dbf0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
dc00: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
dc10: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
dc20: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
dc30: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
dc40: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
dc50: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
dc60: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
dc70: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
dc80: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
dc90: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
dca0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
dcb0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
dcc0: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
dcd0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
dce0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
dcf0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
dd00: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
dd10: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
dd20: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
dd30: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
dd40: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
dd50: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
dd60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dd70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dd80: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
dd90: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
dda0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
ddb0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
ddc0: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
ddd0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dde0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
ddf0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
de00: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
de10: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
de20: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
de30: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
de40: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
de50: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
de60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
de70: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
de80: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
de90: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
dea0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
deb0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dec0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
ded0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
dee0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
def0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
df00: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
df10: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
df20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
df30: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
df40: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
df50: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
df60: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
df70: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
df80: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
df90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
dfa0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
dfb0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
dfc0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
dfd0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
dfe0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
dff0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
e000: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
e010: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
e020: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
e030: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
e040: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
e050: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e060: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e070: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
e080: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
e090: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
e0a0: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
e0b0: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
e0c0: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
e0d0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
e0e0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
e0f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
e100: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
e110: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
e120: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
e130: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
e140: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
e150: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e160: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
e170: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
e180: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
e190: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
e1a0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e1b0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e1c0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
e1d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e1e0: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
e1f0: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
e200: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e210: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e220: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
e230: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
e240: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e250: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e260: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
e270: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e280: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e290: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
e2a0: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
e2b0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
e2c0: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
e2d0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e2e0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
e2f0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
e300: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
e310: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
e320: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
e330: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
e340: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e350: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
e360: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
e370: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
e380: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
e390: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
e3a0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
e3b0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
e3c0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
e3d0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
e3e0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
e3f0: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
e400: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
e410: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e420: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
e430: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
e440: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e450: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
e460: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
e470: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
e480: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
e490: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e4a0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
e4b0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e4c0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
e4d0: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
e4e0: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
e4f0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
e500: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
e510: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
e520: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
e530: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
e540: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
e550: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
e560: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
e570: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e580: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
e590: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
e5a0: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
e5b0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
e5c0: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
e5d0: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
e5e0: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
e5f0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
e600: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
e610: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
e620: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e630: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
e640: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
e650: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
e660: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e670: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
e680: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
e690: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
e6a0: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
e6b0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
e6c0: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
e6d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e6e0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
e6f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
e700: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e710: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
e720: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
e730: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
e740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e750: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
e760: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
e770: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
e780: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
e790: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
e7a0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e7b0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e7c0: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
e7d0: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
e7e0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
e7f0: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
e800: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
e810: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
e820: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
e830: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
e840: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
e850: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
e860: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
e870: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
e880: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
e890: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e8a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
e8b0: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
e8c0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e8d0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
e8e0: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
e8f0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
e900: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
e910: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e920: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
e930: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
e940: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
e950: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
e960: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
e970: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
e980: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
e990: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
e9a0: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
e9b0: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
e9c0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
e9d0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
e9e0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
e9f0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
ea00: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
ea10: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
ea20: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
ea30: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
ea40: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
ea50: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
ea60: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
ea70: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ea80: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ea90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
eaa0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
eab0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
eac0: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
ead0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
eae0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
eaf0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
eb00: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
eb10: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
eb20: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
eb30: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
eb40: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
eb50: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
eb60: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
eb70: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
eb80: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
eb90: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
eba0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
ebb0: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
ebc0: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
ebd0: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
ebe0: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
ebf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ec00: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
ec10: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
ec20: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
ec30: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
ec40: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
ec50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ec60: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
ec70: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
ec80: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
ec90: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
eca0: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
ecb0: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
ecc0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
ecd0: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
ece0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
ecf0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
ed00: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
ed10: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
ed20: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
ed30: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
ed40: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
ed50: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
ed60: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
ed70: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
ed80: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
ed90: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
eda0: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
edb0: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
edc0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
edd0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
ede0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
edf0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
ee00: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
ee10: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
ee20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
ee30: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
ee40: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
ee50: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
ee60: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
ee70: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
ee80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ee90: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
eea0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
eeb0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
eec0: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
eed0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
eee0: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
eef0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
ef00: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
ef10: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
ef20: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
ef30: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
ef40: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ef50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef60: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
ef70: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
ef80: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
ef90: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
efa0: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
efb0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
efc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
efd0: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
efe0: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
eff0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f000: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
f010: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
f020: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
f030: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f040: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
f050: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f060: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
f070: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f080: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f090: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
f0a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f0b0: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
f0c0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f0d0: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
f0e0: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
f0f0: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
f100: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
f110: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
f120: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
f130: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
f140: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
f150: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
f160: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
f170: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
f180: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
f190: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
f1a0: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
f1b0: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
f1c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
f1d0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
f1e0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
f1f0: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
f200: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
f210: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
f220: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
f230: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f240: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f250: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
f260: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
f270: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
f280: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
f290: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f2a0: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
f2b0: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
f2c0: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
f2d0: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
f2e0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
f2f0: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
f300: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
f310: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
f320: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
f330: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
f340: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
f350: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f360: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
f370: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
f380: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
f390: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
f3a0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
f3b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
f3c0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
f3d0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
f3e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f3f0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
f400: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
f410: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
f420: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
f430: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
f440: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f450: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
f460: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
f470: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
f480: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
f490: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
f4a0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
f4b0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
f4c0: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
f4d0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f4e0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
f4f0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f500: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
f510: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
f520: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
f530: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
f540: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
f550: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
f560: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
f570: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
f580: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f590: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
f5a0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
f5b0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f5c0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
f5d0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
f5e0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
f5f0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
f600: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
f610: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f620: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
f630: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
f640: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f650: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f660: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
f670: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
f680: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
f690: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
f6a0: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
f6b0: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
f6c0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f6d0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
f6e0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
f6f0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
f700: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
f710: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
f720: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
f730: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
f740: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f750: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
f760: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
f770: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
f780: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
f790: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
f7a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
f7b0: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
f7c0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
f7d0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
f7e0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
f7f0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
f800: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
f810: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
f820: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
f830: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
f840: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
f850: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
f860: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
f870: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
f880: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
f890: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
f8a0: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
f8b0: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
f8c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
f8d0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
f8e0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
f8f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
f900: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
f910: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
f920: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
f930: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f940: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
f950: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
f960: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
f970: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
f980: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
f990: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f9a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f9b0: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
f9c0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
f9d0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
f9e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9f0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
fa00: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
fa10: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
fa20: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
fa30: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
fa40: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
fa50: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fa60: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
fa70: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
fa80: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
fa90: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
faa0: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
fab0: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
fac0: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
fad0: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
fae0: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
faf0: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
fb00: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
fb10: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
fb20: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
fb30: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
fb40: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
fb50: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
fb60: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
fb70: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
fb80: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fb90: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
fba0: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
fbb0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
fbc0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fbd0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
fbe0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
fbf0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
fc00: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
fc10: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
fc20: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
fc30: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
fc40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fc50: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
fc60: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fc70: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
fc80: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
fc90: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
fca0: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
fcb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
fcc0: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
fcd0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
fce0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
fcf0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
fd00: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
fd10: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
fd20: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
fd30: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
fd40: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
fd50: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
fd60: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
fd70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
fd80: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
fd90: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
fda0: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
fdb0: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
fdc0: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
fdd0: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
fde0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
fdf0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
fe00: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
fe10: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
fe20: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
fe30: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
fe40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
fe50: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
fe60: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
fe70: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
fe80: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
fe90: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
fea0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
feb0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
fec0: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
fed0: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
fee0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
fef0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
ff00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
ff10: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
ff20: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
ff30: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
ff40: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
ff50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ff60: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
ff70: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
ff80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
ff90: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
ffa0: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
ffb0: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
ffc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
ffd0: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
ffe0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fff0: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10000 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10010 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10020 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10030 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10040 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10050 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10060 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10070 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10080 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
10090 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
100a0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
100b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
100c0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
100d0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
100e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
100f0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10100 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10110 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10120 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10130 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10140 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10150 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10160 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10170 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10180 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10190 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
101a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
101b0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
101c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
101d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
101e0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
101f0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10200 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10210 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10220 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10230 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10240 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10250 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
10260 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
10270 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
10280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10290 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
102a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
102b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
102c0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
102d0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
102e0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
102f0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10300 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
10310 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
10320 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
10330 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
10340 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
10350 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
10360 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
10370 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
10380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10390 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
103a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
103b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
103c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
103d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
103e0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
103f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
10400 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10410 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
10420 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
10430 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
10440 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
10450 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
10460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10470 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
10480 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
10490 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
104a0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
104b0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
104c0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
104d0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
104e0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
104f0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
10500 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
10510 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
10520 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
10530 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
10540 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
10550 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
10560 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10570 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
10580 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
10590 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
105a0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
105b0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
105c0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
105d0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
105e0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
105f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10600 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
10610 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
10620 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
10630 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
10640 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
10650 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
10660 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10670 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
10680 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
10690 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
106a0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
106b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
106c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
106d0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
106e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
106f0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10700 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
10710 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10720 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
10730 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
10740 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
10750 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10760 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
10770 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
10780 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
10790 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
107a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
107b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
107c0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
107d0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
107e0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
107f0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10800 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10810 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10820 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10830 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10840 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
10850 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
10860 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
10870 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
10880 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10890 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
108a0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
108b0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
108c0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
108d0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
108e0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
108f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10900 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10910 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10920 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10930 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10940 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10950 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
10960 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10970 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
10980 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
10990 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
109a0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
109b0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
109c0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
109d0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
109e0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
109f0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10a00 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10a10 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10a20 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10a30 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10a40 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
10a50 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
10a60 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
10a70 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10a80 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
10a90 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
10aa0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
10ab0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
10ac0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
10ad0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10ae0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
10af0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10b00 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10b10 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10b20 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
10b30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10b40 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
10b50 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
10b60 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
10b70 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
10b80 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
10b90 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
10ba0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
10bb0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
10bc0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
10bd0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
10be0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
10bf0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
10c00 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
10c10 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
10c20 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
10c30 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
10c40 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
10c50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
10c60 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
10c70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10c80 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
10c90 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
10ca0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
10cb0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10cc0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
10cd0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
10ce0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
10cf0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
10d00 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
10d10 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
10d20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10d30 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
10d40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
10d50 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
10d60 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
10d70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
10d80 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
10d90 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
10da0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10db0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
10dc0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10dd0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
10de0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10df0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
10e00 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
10e10 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
10e20 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
10e30 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
10e40 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
10e50 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
10e60 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
10e70 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
10e80 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
10e90 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
10ea0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
10eb0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
10ec0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
10ed0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
10ee0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
10ef0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
10f00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
10f10 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
10f20 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
10f30 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
10f40 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
10f50 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
10f60 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
10f70 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
10f80 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
10f90 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
10fa0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
10fb0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
10fc0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
10fd0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
10fe0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ff0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
11000 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
11010 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
11020 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
11030 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
11040 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
11050 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11060 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
11070 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
11080 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11090 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
110a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
110b0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
110c0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
110d0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
110e0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
110f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
11100 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
11110 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
11120 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11130 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11140 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11150 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11160 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11170 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
11180 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
11190 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
111a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
111b0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
111c0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
111d0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
111e0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
111f0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
11200 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
11210 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
11220 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11230 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
11240 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
11250 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11260 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
11270 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
11280 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
11290 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
112a0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
112b0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
112c0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
112d0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
112e0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
112f0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
11300 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
11310 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11320 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
11330 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11340 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
11350 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
11360 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11370 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
11380 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
11390 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
113a0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
113b0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
113c0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
113d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
113e0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
113f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11400 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
11410 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
11420 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
11430 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11440 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11450 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
11460 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
11470 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
11480 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
11490 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
114a0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
114b0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
114c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
114d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
114e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
114f0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
11500 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
11510 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
11520 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
11530 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
11540 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11550 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
11560 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11570 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
11580 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
11590 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
115a0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
115b0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
115c0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
115d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
115e0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
115f0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11600 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
11610 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
11620 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
11630 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11640 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11650 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11660 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
11670 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11680 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
11690 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
116a0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
116b0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
116c0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
116d0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
116e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
116f0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11700 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
11710 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11720 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11730 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11740 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11750 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11760 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11770 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11780 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11790 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
117a0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
117b0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
117c0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
117d0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
117e0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
117f0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
11800 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
11810 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
11820 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
11830 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11840 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11850 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11860 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11870 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11880 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11890 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
118a0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
118b0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
118c0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
118d0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
118e0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
118f0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
11900 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11910 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
11920 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11930 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11940 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11950 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
11960 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11970 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11980 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11990 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
119a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
119b0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
119c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
119d0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
119e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
119f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11a00 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11a10 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
11a20 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
11a30 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11a40 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
11a50 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
11a60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11a70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11a80 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11a90 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11aa0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
11ab0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
11ac0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
11ad0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11ae0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
11af0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
11b00 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
11b10 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
11b20 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
11b30 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
11b40 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
11b50 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
11b60 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
11b70 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
11b80 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
11b90 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
11ba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11bb0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
11bc0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
11bd0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11be0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11bf0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11c00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11c10 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11c20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11c30 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11c40 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
11c50 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
11c60 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11c70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11c80 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11c90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11ca0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11cb0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11cc0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
11cd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11ce0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11cf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11d00 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
11d10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11d20 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
11d30 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11d40 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11d50 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11d60 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11d70 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11d80 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
11d90 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
11da0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
11db0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
11dc0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
11dd0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
11de0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
11df0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11e00 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
11e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11e20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
11e30 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
11e40 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
11e50 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
11e60 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
11e70 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11e80 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
11e90 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
11ea0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
11eb0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
11ec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11ed0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
11ee0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
11ef0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
11f00 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
11f10 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
11f20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11f30 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
11f40 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
11f50 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
11f60 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
11f70 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
11f80 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
11f90 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11fa0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11fb0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11fc0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11fd0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11fe0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11ff0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12000 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
12010 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
12020 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12030 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12040 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12050 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12060 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12070 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12080 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
12090 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
120a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
120b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
120c0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
120d0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
120e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
120f0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12100 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12110 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
12120 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
12130 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12140 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12150 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
12160 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12170 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12180 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12190 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
121a0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
121b0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
121c0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
121d0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
121e0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
121f0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
12200 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
12210 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
12220 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
12230 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12240 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12250 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
12260 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12270 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
12280 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
122a0 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
122b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
122c0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
122d0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
122e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
122f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12300 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12310 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12320 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12330 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12340 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
12350 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12360 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
12370 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12380 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12390 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
123a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
123b0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
123c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
123d0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
123e0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
123f0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
12400 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
12410 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
12420 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
12430 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
12440 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
12450 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
12460 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
12470 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12480 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
12490 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
124a0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
124b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
124c0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
124d0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
124e0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
124f0 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
12500 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
12510 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
12520 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
12530 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12540 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
12550 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
12560 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12570 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12580 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
12590 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
125a0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
125b0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
125c0 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
125d0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
125e0 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
125f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12600 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12610 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12620 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
12630 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
12640 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
12650 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
12660 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
12670 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12680 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
12690 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
126a0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
126b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
126c0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
126d0 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
126e0 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
126f0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
12700 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12710 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12720 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12730 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12740 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
12750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12760 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
12770 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
12780 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12790 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
127a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
127b0 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
127c0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
127d0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
127e0 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
127f0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
12800 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
12810 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
12820 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
12830 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
12840 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
12850 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
12860 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
12870 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
12880 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
12890 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
128a0 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
128b0 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
128c0 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
128d0 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
128e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
128f0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
12900 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
12910 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
12920 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
12930 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
12940 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12950 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
12960 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
12970 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
12980 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
12990 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
129a0 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
129b0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
129c0 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
129d0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
129e0 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
129f0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
12a00 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
12a10 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
12a20 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
12a30 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
12a40 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
12a50 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12a60 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
12a70 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
12a80 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
12a90 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
12aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12ab0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
12ac0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
12ad0 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
12ae0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12af0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12b00 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
12b10 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12b20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12b30 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
12b40 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
12b50 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
12b60 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
12b70 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
12b80 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
12b90 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
12ba0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
12bb0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
12bc0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
12bd0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
12be0 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
12bf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
12c00 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
12c10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
12c20 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
12c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12c40 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
12c50 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
12c60 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12c70 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
12c80 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
12c90 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
12ca0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
12cb0 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
12cc0 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
12cd0 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
12ce0 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
12cf0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
12d00 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
12d10 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
12d20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
12d30 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
12d40 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
12d50 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
12d60 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
12d70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
12d80 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
12d90 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
12da0 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
12db0 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
12dc0 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
12dd0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
12de0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
12df0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
12e00 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
12e10 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
12e20 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
12e30 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
12e40 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
12e50 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
12e60 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
12e70 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
12e80 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
12e90 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
12ea0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12eb0 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
12ec0 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
12ed0 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
12ee0 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
12ef0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
12f00 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
12f10 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
12f20 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
12f30 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
12f40 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
12f50 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
12f60 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
12f70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12f80 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
12f90 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
12fa0 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
12fb0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12fc0 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
12fd0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
12fe0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
12ff0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
13000 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
13010 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
13020 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
13030 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13040 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
13050 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
13060 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13070 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
13080 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
13090 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
130a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
130b0 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
130c0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
130d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
130e0 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
130f0 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
13100 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
13110 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
13120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13130 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
13140 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13150 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
13160 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
13170 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
13180 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
13190 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
131a0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
131b0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
131c0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
131d0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
131e0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
131f0 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
13200 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
13210 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
13220 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
13230 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13240 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
13250 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
13260 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
13270 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
13280 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
13290 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
132a0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
132b0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
132c0 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
132d0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
132e0 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
132f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
13300 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
13310 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
13320 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13330 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13340 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13350 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
13360 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
13370 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
13380 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
13390 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
133a0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
133b0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
133c0 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
133d0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
133e0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
133f0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13400 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13410 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13420 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13430 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13440 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13450 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13460 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
13470 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
13480 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
13490 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
134a0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
134b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
134c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
134d0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
134e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
134f0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13500 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
13510 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13520 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13530 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13540 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
13550 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
13560 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
13570 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
13580 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
13590 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
135a0 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
135b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
135c0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
135d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
135e0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
135f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13600 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13610 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
13620 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13630 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
13640 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
13650 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13660 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13670 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13680 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13690 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
136a0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
136b0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
136c0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
136d0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
136e0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
136f0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
13700 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13710 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13720 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
13730 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
13740 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
13750 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
13760 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13770 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13780 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13790 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
137a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
137b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
137c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
137d0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
137e0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
137f0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13800 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13810 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13820 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
13830 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13840 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13850 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13860 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13870 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
13880 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
13890 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
138a0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
138b0 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
138c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
138d0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
138e0 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
138f0 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
13900 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
13910 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
13920 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
13930 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
13940 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13950 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13960 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13970 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13980 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13990 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
139a0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
139b0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
139c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
139d0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
139e0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
139f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13a00 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13a10 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
13a20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13a30 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13a40 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13a50 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13a60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13a70 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
13a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13a90 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
13aa0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13ab0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
13ac0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
13ad0 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
13ae0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
13af0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
13b00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
13b10 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
13b20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13b30 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
13b40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
13b50 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
13b60 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
13b70 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
13b80 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
13b90 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
13ba0 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
13bb0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
13bc0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
13bd0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
13be0 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
13bf0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
13c00 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
13c10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13c20 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
13c30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13c40 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
13c50 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
13c60 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
13c70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
13c80 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
13c90 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
13ca0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13cb0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
13cc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13cd0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
13ce0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
13cf0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13d00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13d10 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
13d20 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
13d30 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
13d40 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
13d50 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
13d60 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
13d70 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
13d80 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13d90 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
13da0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13db0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
13dc0 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
13dd0 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
13de0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13df0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
13e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13e10 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
13e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13e30 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13e40 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13e50 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13e60 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13e70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13e80 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
13e90 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13ea0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
13eb0 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
13ec0 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
13ed0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13ee0 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
13ef0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
13f00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13f10 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
13f20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
13f30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
13f40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13f50 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
13f60 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
13f70 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
13f80 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
13f90 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
13fa0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
13fb0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
13fc0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
13fd0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
13fe0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
13ff0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
14000 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
14010 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
14020 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
14030 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
14040 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
14050 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
14060 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
14070 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14080 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
14090 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
140a0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
140b0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
140c0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
140d0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
140e0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
140f0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
14100 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
14110 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14120 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
14130 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
14140 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
14150 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
14160 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
14170 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14180 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14190 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
141a0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
141b0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
141c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
141d0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
141e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
141f0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
14200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14210 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
14220 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
14230 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
14240 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
14250 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
14260 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
14270 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
14280 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
14290 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
142a0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
142b0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
142c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
142d0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
142e0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
142f0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
14300 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
14310 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
14320 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
14330 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
14340 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
14350 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
14360 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14370 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
14380 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
14390 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
143a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
143b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
143c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
143d0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
143e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
143f0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
14400 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
14410 64 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  dd>^(This option
14420 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14430 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
14440 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
14450 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
14460 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14470 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
14480 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
14490 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
144a0 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
144b0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
144c0 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
144d0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
144e0 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
144f0 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
14500 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
14510 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
14520 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
14530 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
14540 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
14550 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
14560 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
14570 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
14580 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
14590 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
145a0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
145b0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
145c0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
145d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
145e0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
145f0 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
14600 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
14610 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
14620 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
14630 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
14640 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
14650 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
14660 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
14670 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
14680 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
14690 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
146a0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
146b0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
146c0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
146d0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
146e0 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
146f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
14700 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
14710 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
14720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14730 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14740 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
14750 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14760 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
14770 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  >^This option ta
14780 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
14790 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
147a0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
147b0 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
147c0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
147d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
147e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
147f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
14800 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
14810 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
14820 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54  y optimizer.  ^T
14830 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14840 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
14850 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
14860 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
14870 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
14880 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14890 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
148a0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
148b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
148c0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
148d0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
148e0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
148f0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14900 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14910 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
14920 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
14930 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
14940 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
14950 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
14960 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
14970 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
14980 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
14990 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
149a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
149b0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
149c0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
149d0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
149e0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
149f0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
14a00 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
14a10 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
14a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14a30 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
14a40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14a50 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
14a60 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14a70 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
14a80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14a90 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
14aa0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
14ab0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
14ac0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
14ad0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
14ae0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
14af0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
14b00 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
14b10 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
14b20 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14b30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14b40 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
14b50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
14b60 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
14b70 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
14b80 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
14b90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14ba0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14bb0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
14bc0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
14bd0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
14be0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14bf0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
14c00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
14c10 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
14c20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
14c30 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
14c40 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
14c50 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
14c60 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
14c70 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
14c80 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
14c90 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
14ca0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
14cb0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
14cc0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
14cd0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
14ce0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
14cf0 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
14d00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14d10 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
14d20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14d30 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
14d40 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14d50 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
14d60 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
14d70 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
14d80 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
14d90 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
14da0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
14db0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
14dc0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
14dd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14de0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
14df0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
14e00 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14e10 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
14e20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
14e30 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
14e40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
14e50 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
14e60 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
14e70 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
14e80 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14e90 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
14ea0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
14eb0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
14ec0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
14ed0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
14ee0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
14ef0 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
14f00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
14f10 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
14f20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
14f30 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
14f40 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
14f50 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
14f60 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
14f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14f80 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
14f90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14fa0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
14fb0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
14fc0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
14fd0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
14fe0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
14ff0 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
15000 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
15010 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
15020 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
15030 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
15040 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15050 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
15060 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15070 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
15080 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15090 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
150a0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
150b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
150c0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
150d0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
150e0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
150f0 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
15100 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
15110 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
15120 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
15130 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15140 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63  d mmap size.** c
15150 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
15160 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e   at run-time.  N
15170 6f 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d  or may the maxim
15180 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15190 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74  size.** exceed t
151a0 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
151b0 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
151c0 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
151d0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
151e0 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
151f0 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
15200 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
15210 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
15220 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
15230 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
15240 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
15250 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
15260 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
15270 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15280 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15290 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
152a0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
152b0 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
152c0 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  >^This option is
152d0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
152e0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
152f0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
15300 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  s.** with the [S
15310 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
15320 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
15330 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15340 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
15350 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15360 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
15370 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
15380 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
15390 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
153a0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
153b0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
153c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
153d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
153e0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
153f0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15400 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15410 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
15420 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
15430 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15440 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
15450 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
15460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15470 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
15480 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
15490 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
154a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
154b0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
154c0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
154d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
154e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
154f0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
15500 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
15510 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15530 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15540 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
15550 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
15560 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
15570 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15580 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
15590 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
155a0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
155b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
155c0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
155d0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
155e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
155f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
15600 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
15610 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15620 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15640 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
15650 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15660 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
15670 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
15680 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
15690 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
156a0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
156b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
156c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
156d0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
156e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
156f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
15700 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
15710 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15720 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15730 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
15740 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
15750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15760 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
15770 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
15780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15790 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
157a0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
157b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157c0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
157d0 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
157e0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
157f0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
15800 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15810 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
15820 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
15830 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
15840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15850 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15860 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
15870 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
15880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15890 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
158a0 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
158b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
158c0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
158d0 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
158e0 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
158f0 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
15900 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15910 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15920 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
15930 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
15940 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
15950 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
15960 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
15970 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
15980 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
15990 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
159a0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
159b0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
159c0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
159d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
159e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
159f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15a00 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
15a10 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
15a20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15a30 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
15a40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
15a50 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
15a60 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
15a70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
15a80 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
15a90 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
15aa0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
15ab0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
15ac0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
15ad0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
15ae0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
15af0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
15b00 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
15b10 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15b20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
15b30 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
15b40 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
15b50 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
15b60 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
15b70 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
15b80 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
15b90 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
15ba0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
15bb0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15bc0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
15bd0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15be0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
15bf0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
15c00 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
15c10 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
15c20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
15c30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
15c40 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
15c50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
15c60 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
15c70 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
15c80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
15c90 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15ca0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
15cb0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
15cc0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
15cd0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15ce0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
15cf0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
15d00 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
15d10 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
15d20 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
15d30 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
15d40 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
15d50 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
15d60 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
15d70 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
15d80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
15d90 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15da0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
15db0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
15dc0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
15dd0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
15de0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
15df0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
15e00 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
15e10 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
15e20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
15e30 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
15e40 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
15e50 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
15e60 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
15e70 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
15e80 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
15e90 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
15ea0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
15eb0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
15ec0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15ed0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
15ee0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15ef0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
15f00 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
15f10 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
15f20 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
15f30 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
15f40 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
15f50 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
15f60 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
15f70 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
15f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15f90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
15fa0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
15fb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
15fc0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
15fd0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
15fe0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
15ff0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
16000 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
16010 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
16020 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
16030 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
16040 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16050 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
16060 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
16070 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16080 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
16090 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
160a0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
160b0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
160c0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
160d0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
160e0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
160f0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
16100 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
16110 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16120 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
16130 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16140 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16150 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16160 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
16170 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
16180 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
16190 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
161a0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
161b0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
161c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
161d0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
161e0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
161f0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
16200 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
16210 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16220 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16230 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16240 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16250 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
16260 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16270 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16280 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16290 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
162a0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
162b0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
162c0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
162d0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
162e0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
162f0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16300 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16310 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16320 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16330 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16340 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16350 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16360 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16370 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16380 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16390 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
163a0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
163b0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
163c0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
163d0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
163e0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
163f0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16400 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16410 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16420 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16430 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16440 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16450 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
16460 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16470 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
16480 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16490 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
164a0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
164b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
164c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
164d0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
164e0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
164f0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16500 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16510 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
16520 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
16530 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
16540 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16550 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
16560 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
16570 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
16580 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
16590 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
165a0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
165b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
165c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
165d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
165e0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
165f0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
16600 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16610 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16620 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
16630 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
16640 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16650 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16660 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
16670 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
16680 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
16690 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
166a0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
166b0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
166c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
166d0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
166e0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
166f0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
16700 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
16710 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
16720 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
16730 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
16740 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
16750 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
16760 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
16770 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
16780 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
16790 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
167a0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
167b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
167c0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
167d0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
167e0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
167f0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
16800 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
16810 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
16820 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
16830 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
16840 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
16850 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
16860 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
16870 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
16880 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
16890 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
168a0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
168b0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
168c0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
168d0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
168e0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
168f0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
16900 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
16910 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
16920 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
16930 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
16940 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
16950 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
16960 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
16970 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
16980 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
16990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
169a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
169b0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
169c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
169d0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
169e0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
169f0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
16a00 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
16a10 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
16a20 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
16a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16a40 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
16a50 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
16a60 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
16a70 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
16a80 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
16a90 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
16aa0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
16ab0 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
16ac0 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
16ad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16ae0 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
16af0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16b00 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
16b10 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
16b20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
16b30 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
16b40 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
16b50 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
16b60 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
16b70 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
16b80 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
16b90 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
16ba0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
16bb0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
16bc0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
16bd0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
16be0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
16bf0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
16c00 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
16c10 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
16c20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16c30 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
16c40 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
16c50 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
16c60 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
16c70 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
16c80 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
16c90 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
16ca0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
16cb0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
16cc0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
16cd0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
16ce0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16cf0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
16d00 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
16d10 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
16d20 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
16d30 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
16d40 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
16d50 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
16d60 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
16d70 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
16d80 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
16d90 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
16da0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
16db0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
16dc0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
16dd0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
16de0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
16df0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
16e00 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
16e10 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
16e20 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
16e30 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
16e40 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
16e50 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
16e60 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
16e70 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
16e80 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
16e90 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
16ea0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
16eb0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
16ec0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
16ed0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
16ee0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
16ef0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
16f00 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
16f10 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
16f20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
16f30 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
16f40 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
16f50 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
16f60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
16f70 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
16f80 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
16f90 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
16fa0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
16fb0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
16fc0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
16fd0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
16fe0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
16ff0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17010 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17020 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17030 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17040 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17050 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17060 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17070 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17080 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17090 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
170a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
170b0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
170c0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
170d0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
170e0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
170f0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17100 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17110 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17120 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17130 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17140 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17150 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17160 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17170 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
17180 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17190 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
171a0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
171b0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
171c0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
171d0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
171e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
171f0 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
17200 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
17210 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
17220 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
17230 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
17240 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
17250 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
17260 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
17270 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17280 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
17290 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
172a0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
172b0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
172c0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
172d0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
172e0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
172f0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
17300 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
17310 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
17320 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17330 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
17340 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
17350 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
17360 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
17370 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
17380 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
17390 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
173a0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
173b0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
173c0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
173d0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
173e0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
173f0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
17400 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
17410 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
17420 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
17430 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
17440 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
17450 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
17460 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
17470 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
17480 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
17490 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
174a0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
174b0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
174c0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
174d0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
174e0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
174f0 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
17500 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
17510 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
17520 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
17530 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
17540 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
17550 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
17560 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
17570 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
17580 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
17590 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
175a0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
175b0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
175c0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
175d0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
175e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
175f0 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
17600 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
17610 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
17620 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
17630 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
17640 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
17650 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
17660 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
17670 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
17680 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
17690 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
176a0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
176b0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
176c0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
176d0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
176e0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
176f0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
17700 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
17710 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17720 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
17730 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
17740 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
17750 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
17760 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
17770 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
17780 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
17790 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
177a0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
177b0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
177c0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
177d0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
177e0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
177f0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
17800 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
17810 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
17820 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
17830 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
17840 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
17850 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
17860 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17870 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
17880 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
17890 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
178a0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
178b0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
178c0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
178d0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
178e0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
178f0 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
17900 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
17910 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
17920 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17930 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17940 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17950 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
17960 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
17970 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
17980 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
17990 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
179a0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
179b0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
179c0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
179d0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
179e0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
179f0 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
17a00 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
17a10 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17a20 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17a30 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
17a40 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
17a50 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
17a60 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17a70 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17a80 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
17a90 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
17aa0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
17ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17ac0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
17ad0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17ae0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17af0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
17b00 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17b10 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17b20 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
17b30 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
17b40 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17b50 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
17b60 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
17b70 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
17b80 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17b90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17ba0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
17bb0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
17bc0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
17bd0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
17be0 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
17bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17c00 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
17c10 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
17c20 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
17c30 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17c40 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
17c50 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
17c60 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
17c70 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
17c80 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
17c90 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
17ca0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
17cb0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
17cc0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
17cd0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
17ce0 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
17cf0 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
17d00 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
17d10 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
17d20 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
17d30 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
17d40 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
17d50 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
17d60 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
17d70 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
17d80 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
17d90 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
17da0 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
17db0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17dc0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
17dd0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
17de0 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
17df0 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
17e00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
17e10 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
17e20 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
17e30 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
17e40 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
17e50 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
17e60 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
17e70 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
17e80 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
17e90 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
17ea0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
17eb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
17ec0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
17ed0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
17ee0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
17ef0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
17f00 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
17f10 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
17f20 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
17f30 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17f40 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17f50 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
17f60 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
17f70 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
17f80 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
17f90 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
17fa0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
17fb0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
17fc0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
17fd0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
17fe0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
17ff0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
18000 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
18010 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
18020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18030 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
18040 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
18050 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
18060 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
18070 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
18080 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
18090 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
180a0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
180b0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
180c0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
180d0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
180e0 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
180f0 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
18100 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
18110 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
18120 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
18130 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
18140 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
18150 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
18160 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
18170 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
18180 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
18190 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
181a0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
181b0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
181c0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
181d0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
181e0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
181f0 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
18200 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
18210 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
18220 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
18230 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
18240 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
18250 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
18260 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18270 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
18280 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
18290 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
182a0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
182b0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
182c0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
182d0 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
182e0 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
182f0 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
18300 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
18310 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
18320 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
18330 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
18340 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
18350 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
18360 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
18370 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
18380 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
18390 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
183a0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
183b0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
183c0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
183d0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
183e0 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
183f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
18400 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
18410 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
18420 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
18430 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
18440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18450 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
18460 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
18470 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
18480 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
18490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
184a0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
184b0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
184c0 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
184d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
184e0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
184f0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
18500 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18510 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
18520 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
18530 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
18540 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
18550 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
18560 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
18570 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
18580 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18590 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
185a0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
185b0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
185c0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
185d0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
185e0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
185f0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
18600 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
18610 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18620 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
18630 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
18640 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
18650 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
18660 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
18670 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
18680 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
18690 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
186a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
186b0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
186c0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
186d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
186e0 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
186f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
18700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18710 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
18720 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18730 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
18740 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
18750 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
18760 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
18770 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18780 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18790 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
187a0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
187b0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
187c0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
187d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
187e0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
187f0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
18800 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
18810 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
18820 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
18830 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
18840 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
18850 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
18860 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
18870 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
18880 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
18890 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
188a0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
188b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
188c0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
188d0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
188e0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
188f0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
18900 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
18910 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
18920 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
18930 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
18940 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
18950 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
18960 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
18970 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
18980 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
18990 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
189a0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
189b0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
189c0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
189d0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
189e0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
189f0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
18a00 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
18a10 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
18a20 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
18a30 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
18a40 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
18a50 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
18a60 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
18a70 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
18a80 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
18a90 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
18aa0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
18ab0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
18ac0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
18ad0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
18ae0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
18af0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
18b00 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
18b10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18b20 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
18b30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
18b40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
18b50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
18b60 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
18b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
18b80 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
18b90 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
18ba0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
18bb0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
18bc0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
18bd0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
18be0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
18bf0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
18c00 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
18c10 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
18c20 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
18c30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18c40 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
18c50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
18c60 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18c70 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
18c80 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
18c90 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
18ca0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
18cb0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
18cc0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
18cd0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
18ce0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
18cf0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
18d00 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
18d10 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
18d20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18d30 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
18d40 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
18d50 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
18d60 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
18d70 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
18d80 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18d90 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
18da0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18db0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
18dc0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
18dd0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
18de0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
18df0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
18e00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
18e10 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
18e20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
18e30 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
18e40 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
18e50 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
18e60 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
18e70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
18e80 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
18e90 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
18ea0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
18eb0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
18ec0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
18ed0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
18ee0 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
18ef0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
18f00 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
18f10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
18f20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
18f30 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
18f40 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
18f50 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
18f60 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
18f70 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
18f80 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
18f90 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
18fa0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
18fb0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
18fc0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
18fd0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
18fe0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
18ff0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
19000 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19010 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
19020 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
19030 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
19040 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
19050 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
19060 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
19070 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
19080 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
19090 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
190a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
190b0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
190c0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
190d0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
190e0 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
190f0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
19100 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
19110 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
19120 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19130 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
19140 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
19150 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
19160 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19170 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
19180 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
19190 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
191a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
191b0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
191c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
191d0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
191e0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
191f0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
19200 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
19210 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
19220 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
19230 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
19240 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
19250 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
19260 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
19270 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
19280 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
19290 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
192a0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
192b0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
192c0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
192d0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
192e0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
192f0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
19300 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
19310 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
19320 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19330 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
19340 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
19350 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
19360 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
19370 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
19380 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
19390 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
193a0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
193b0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
193c0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
193d0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
193e0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
193f0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
19400 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
19410 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
19420 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
19430 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
19440 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
19450 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
19460 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
19470 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
19480 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
19490 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
194a0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
194b0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
194c0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
194d0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
194e0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
194f0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
19500 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
19510 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
19520 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
19530 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
19540 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
19550 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19560 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
19570 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
19580 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
19590 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
195a0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
195b0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
195c0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
195d0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
195e0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
195f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
19600 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
19610 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
19620 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
19630 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
19640 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
19650 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
19660 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
19670 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
19680 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
19690 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
196a0 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
196b0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
196c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
196d0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
196e0 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
196f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
19700 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
19710 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
19720 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
19730 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
19740 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
19750 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
19760 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
19770 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
19780 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
19790 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
197a0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
197b0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
197c0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
197d0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
197e0 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
197f0 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
19800 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
19810 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
19820 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
19830 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
19840 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
19850 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
19860 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
19870 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
19880 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
19890 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
198a0 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
198b0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
198c0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
198d0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
198e0 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
198f0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
19900 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
19910 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
19920 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
19930 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
19940 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
19950 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
19960 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
19970 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
19980 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
19990 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
199a0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
199b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
199c0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
199d0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
199e0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
199f0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
19a00 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
19a10 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
19a20 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19a30 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
19a40 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
19a50 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
19a60 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
19a70 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
19a80 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
19a90 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
19aa0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
19ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
19ac0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19ad0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
19ae0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
19af0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
19b00 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
19b10 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
19b20 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
19b30 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
19b40 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
19b50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
19b60 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
19b70 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
19b80 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
19b90 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19ba0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
19bb0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
19bc0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
19bd0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
19be0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
19bf0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
19c00 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
19c10 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
19c20 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
19c30 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
19c40 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
19c50 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
19c60 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
19c70 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
19c80 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
19c90 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
19ca0 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
19cb0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
19cc0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
19cd0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
19ce0 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
19cf0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
19d00 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
19d10 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
19d20 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
19d30 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
19d40 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
19d50 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
19d60 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
19d70 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
19d80 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
19d90 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
19da0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
19db0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
19dc0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
19dd0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
19de0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
19df0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
19e00 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
19e10 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
19e20 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
19e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
19e40 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
19e50 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
19e60 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
19e70 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
19e80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
19e90 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
19ea0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
19eb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
19ec0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
19ed0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
19ee0 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  d.)^.*/.int sqli
19ef0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19f00 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
19f10 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
19f20 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
19f30 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
19f40 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
19f50 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
19f60 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
19f70 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
19f80 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
19f90 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
19fa0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
19fb0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
19fc0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
19fd0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
19fe0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
19ff0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1a000 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1a010 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1a020 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a030 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1a040 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1a050 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1a060 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1a070 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1a080 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1a090 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1a0a0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1a0b0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1a0c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1a0d0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1a0e0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1a0f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1a100 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1a110 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1a120 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1a130 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1a140 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a150 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1a160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a170 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1a180 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1a190 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1a1a0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1a1b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1a1c0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1a1d0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1a1e0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1a1f0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1a200 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1a210 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1a220 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1a230 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1a240 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1a250 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1a260 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1a270 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1a280 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1a290 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1a2a0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1a2b0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1a2c0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1a2d0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1a2e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1a2f0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1a300 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1a310 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1a320 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1a330 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1a340 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1a350 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1a360 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1a370 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1a380 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1a390 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1a3a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1a3b0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1a3c0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1a3d0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1a3e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1a3f0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1a400 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1a410 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1a420 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1a430 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1a440 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1a450 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a460 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a470 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1a480 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1a490 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1a4a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1a4b0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1a4c0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1a4d0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1a4e0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1a4f0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1a500 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a510 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1a520 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1a530 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1a540 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1a550 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1a560 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1a570 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1a580 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1a590 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1a5a0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1a5b0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1a5c0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1a5d0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1a5e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a5f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1a600 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1a610 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1a620 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a630 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1a640 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a650 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1a660 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a670 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1a680 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a690 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1a6a0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1a6b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1a6c0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1a6d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1a6e0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1a6f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a700 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1a710 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a720 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1a730 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1a740 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1a750 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1a760 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1a770 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1a780 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1a790 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1a7a0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1a7b0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1a7c0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1a7d0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1a7e0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1a7f0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1a800 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1a810 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1a820 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1a830 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1a840 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1a850 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a860 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1a870 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1a880 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1a890 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1a8a0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1a8b0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1a8c0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1a8d0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1a8e0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1a8f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1a900 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1a910 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1a920 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1a930 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1a940 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1a950 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1a960 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1a970 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1a980 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1a990 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1a9a0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1a9b0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1a9c0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1a9d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a9e0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1a9f0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1aa00 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1aa10 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1aa20 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1aa30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1aa40 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1aa50 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1aa60 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1aa70 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1aa80 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1aa90 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1aaa0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1aab0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1aac0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1aad0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1aae0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1aaf0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1ab00 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1ab10 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1ab20 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1ab30 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1ab40 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1ab50 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1ab60 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1ab70 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1ab80 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1ab90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1aba0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1abb0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1abc0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1abd0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1abe0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1abf0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1ac00 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1ac10 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1ac20 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1ac30 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1ac40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1ac50 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1ac60 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1ac70 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1ac80 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1ac90 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1aca0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1acb0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1acc0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1acd0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1ace0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1acf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1ad00 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1ad10 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1ad20 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1ad30 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1ad40 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1ad50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1ad60 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1ad70 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1ad80 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1ad90 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1ada0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1adb0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
1adc0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1add0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1ade0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1adf0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1ae00 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1ae10 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1ae20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1ae30 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1ae40 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1ae50 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1ae60 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1ae70 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1ae80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ae90 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1aea0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1aeb0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1aec0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1aed0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1aee0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1aef0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1af00 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1af10 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1af20 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1af30 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1af40 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1af50 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1af60 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1af70 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1af80 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1af90 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1afa0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1afb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1afc0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1afd0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1afe0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1aff0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1b000 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1b010 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1b020 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1b030 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1b040 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1b050 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1b060 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1b070 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1b080 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1b090 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1b0a0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1b0b0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1b0c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b0d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b0e0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1b0f0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1b100 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1b110 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1b120 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1b130 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1b140 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1b150 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1b160 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1b170 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1b180 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1b190 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1b1a0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1b1b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b1c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b1d0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1b1e0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1b1f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1b200 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1b210 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1b220 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1b230 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1b240 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1b250 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1b260 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1b270 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1b280 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1b290 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1b2a0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1b2b0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1b2c0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1b2d0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1b2e0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1b2f0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1b300 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1b310 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1b320 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1b330 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1b340 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1b350 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b360 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1b370 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1b380 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1b390 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b3a0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1b3b0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1b3c0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1b3d0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1b3e0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1b3f0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1b400 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1b410 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1b420 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1b430 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1b440 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1b450 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1b460 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1b470 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1b480 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1b490 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1b4a0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1b4b0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1b4c0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1b4d0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1b4e0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1b4f0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1b500 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1b510 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1b520 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1b530 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1b540 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1b550 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1b560 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1b570 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1b580 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1b590 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1b5a0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1b5b0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1b5c0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1b5d0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1b5e0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1b5f0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1b600 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1b610 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b620 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1b630 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1b640 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1b650 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b660 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1b670 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1b680 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1b690 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1b6a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b6b0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1b6c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b6d0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1b6e0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1b6f0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1b700 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1b710 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1b720 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1b730 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1b740 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b750 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1b760 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1b770 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1b780 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1b790 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1b7a0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1b7b0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1b7c0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b7d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b7e0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1b7f0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1b800 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1b810 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1b820 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b830 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1b840 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1b850 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1b860 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1b870 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1b880 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1b890 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1b8a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b8b0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1b8c0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1b8d0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1b8e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b8f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1b900 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1b910 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1b920 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1b930 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1b940 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1b950 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1b960 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1b970 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1b980 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1b990 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1b9a0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b9b0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1b9c0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1b9d0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1b9e0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1b9f0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1ba00 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1ba10 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1ba20 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1ba30 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1ba40 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1ba50 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1ba60 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1ba70 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1ba80 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1ba90 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1baa0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1bab0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bac0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1bad0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1bae0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1baf0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1bb00 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1bb10 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1bb20 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1bb30 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1bb40 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1bb50 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1bb60 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1bb70 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1bb80 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1bb90 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1bba0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1bbb0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1bbc0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1bbd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1bbe0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1bbf0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1bc00 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1bc10 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1bc20 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1bc30 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1bc40 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1bc50 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1bc60 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1bc70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1bc80 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1bc90 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1bca0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1bcb0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1bcc0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1bcd0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1bce0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1bcf0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1bd00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1bd10 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1bd20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1bd30 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1bd40 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1bd50 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1bd60 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1bd70 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1bd80 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1bd90 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1bda0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1bdb0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1bdc0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1bdd0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1bde0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1bdf0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1be00 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1be10 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1be20 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1be30 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1be40 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1be50 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1be60 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1be70 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1be80 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1be90 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1bea0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1beb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bec0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1bed0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1bee0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1bef0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1bf00 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1bf10 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1bf20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1bf30 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bf40 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1bf50 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1bf60 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1bf70 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1bf80 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1bf90 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1bfa0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1bfb0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1bfc0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1bfd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bfe0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1bff0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c000 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1c010 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1c020 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1c030 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1c040 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1c050 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1c060 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1c070 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1c080 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1c090 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1c0a0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1c0b0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1c0c0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1c0d0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1c0e0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1c0f0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1c100 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1c110 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1c120 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1c130 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1c140 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1c150 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1c160 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1c170 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1c180 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1c190 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1c1a0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1c1b0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1c1c0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1c1d0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1c1e0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1c1f0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1c200 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1c210 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1c220 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c230 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1c240 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1c250 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1c260 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1c270 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c280 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c290 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
1c2a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1c2b0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
1c2c0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1c2d0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1c2e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c2f0 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1c300 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
1c310 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
1c320 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1c330 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c340 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
1c350 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
1c360 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
1c370 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
1c380 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c390 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1c3a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1c3b0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1c3c0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1c3d0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1c3e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
1c3f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1c400 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1c410 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1c420 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
1c430 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c440 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1c450 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1c460 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1c470 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1c480 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1c490 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1c4a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
1c4b0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
1c4c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1c4d0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1c4e0 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
1c4f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1c500 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c510 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1c520 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1c530 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1c540 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
1c550 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1c560 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
1c570 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1c580 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1c590 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1c5a0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1c5b0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1c5c0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1c5d0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1c5e0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1c5f0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1c600 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1c610 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
1c620 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1c630 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1c640 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c650 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
1c660 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
1c670 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
1c680 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1c690 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1c6a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1c6b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
1c6c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c6d0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1c6e0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1c6f0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1c700 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1c710 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1c720 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1c730 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1c740 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1c750 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1c760 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1c770 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1c780 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1c790 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1c7a0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1c7b0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1c7c0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1c7d0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1c7e0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1c7f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c800 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1c810 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1c820 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1c830 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1c840 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1c850 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1c860 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1c870 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1c880 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1c890 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
1c8a0 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
1c8b0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1c8c0 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
1c8d0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
1c8e0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
1c8f0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
1c900 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
1c910 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
1c920 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
1c930 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
1c940 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
1c950 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
1c960 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
1c970 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
1c980 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
1c990 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c9a0 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
1c9b0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
1c9c0 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
1c9d0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1c9e0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1c9f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1ca00 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1ca10 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1ca20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1ca30 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1ca40 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1ca50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ca60 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1ca70 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1ca80 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1ca90 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1caa0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1cab0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1cac0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1cad0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1cae0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1caf0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1cb00 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1cb10 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1cb20 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1cb30 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1cb40 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1cb50 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1cb60 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1cb70 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1cb80 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1cb90 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
1cba0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1cbb0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
1cbc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1cbd0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1cbe0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1cbf0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1cc00 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1cc10 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1cc20 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1cc30 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1cc40 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1cc50 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1cc60 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1cc70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1cc80 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1cc90 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1cca0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ccb0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1ccc0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1ccd0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1cce0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1ccf0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1cd00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1cd10 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1cd20 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1cd30 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1cd40 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1cd50 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1cd60 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1cd70 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1cd80 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cd90 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1cda0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1cdb0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1cdc0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1cdd0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1cde0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1cdf0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1ce00 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1ce10 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1ce20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1ce30 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1ce40 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1ce50 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1ce60 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1ce70 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1ce80 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1ce90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1cea0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1ceb0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1cec0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1ced0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1cee0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1cef0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1cf00 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1cf10 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1cf20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1cf30 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1cf40 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1cf50 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1cf60 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1cf70 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1cf80 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1cf90 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1cfa0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1cfb0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1cfc0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1cfd0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1cfe0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1cff0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1d000 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1d010 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1d020 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1d030 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
1d040 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d050 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
1d060 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1d070 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1d080 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1d090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d0a0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1d0b0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1d0c0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1d0d0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1d0e0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1d0f0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1d100 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1d110 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1d120 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1d130 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1d140 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1d150 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1d160 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1d170 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1d180 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1d190 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1d1a0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1d1b0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1d1c0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1d1d0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1d1e0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1d1f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1d200 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1d210 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1d220 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1d230 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1d240 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1d250 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1d260 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1d270 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1d280 50 2e 0a 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c  P..** ^If N is l
1d290 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68  ess than one, th
1d2a0 65 6e 20 50 20 63 61 6e 20 62 65 20 61 20 4e 55  en P can be a NU
1d2b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1d2c0 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  * ^If this routi
1d2d0 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  ne has not been 
1d2e0 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65  previously calle
1d2f0 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76  d or if the prev
1d300 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64  ious.** call had
1d310 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65   N less than one
1d320 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
1d330 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
1d340 72 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62  randomness.** ob
1d350 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
1d360 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1d370 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1d380 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1d390 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1d3a0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1d3b0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1d3c0 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1d3d0 72 20 6d 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74  r more then.** t
1d3e0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1d3f0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1d400 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1d410 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1d420 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1d430 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1d440 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1d450 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1d460 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1d470 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1d480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1d490 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1d4a0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1d4b0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
1d4c0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1d4d0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1d4e0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1d4f0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1d500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d510 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1d520 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1d530 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1d540 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d550 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1d560 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1d570 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1d580 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1d590 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1d5a0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1d5b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d5c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1d5d0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1d5e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d5f0 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1d600 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1d610 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1d620 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1d630 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1d640 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1d650 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1d660 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1d670 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d680 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1d690 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1d6a0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1d6b0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1d6c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1d6d0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1d6e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1d6f0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1d700 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1d710 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1d720 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1d730 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1d740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1d750 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1d760 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1d770 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1d780 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1d790 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1d7a0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1d7b0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1d7c0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1d7d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1d7e0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1d7f0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1d800 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1d810 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1d820 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1d830 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1d840 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d850 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1d860 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1d870 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1d880 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1d890 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1d8a0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1d8b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1d8c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1d8d0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1d8e0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1d8f0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1d900 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1d910 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1d920 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1d930 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d940 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1d950 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1d960 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1d970 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1d980 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1d990 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1d9a0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1d9b0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1d9c0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1d9d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1d9e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d9f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1da00 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1da10 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1da20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1da30 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1da40 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1da50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1da60 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1da70 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1da80 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1da90 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1daa0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1dab0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1dac0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1dad0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1dae0 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1daf0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1db00 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1db10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1db20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1db30 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1db40 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1db50 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1db60 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1db70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1db80 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1db90 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1dba0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1dbb0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1dbc0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1dbd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dbe0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1dbf0 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1dc00 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1dc10 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1dc20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1dc30 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1dc40 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1dc50 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1dc60 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1dc70 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1dc80 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1dc90 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1dca0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1dcb0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1dcc0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1dcd0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1dce0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1dcf0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1dd00 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1dd10 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1dd20 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1dd30 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1dd40 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1dd50 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1dd60 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1dd70 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1dd80 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1dd90 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1dda0 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1ddb0 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1ddc0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1ddd0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1dde0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1ddf0 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1de00 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1de10 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1de20 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1de30 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1de40 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1de50 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1de60 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1de70 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1de80 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1de90 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1dea0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1deb0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1dec0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1ded0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1dee0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1def0 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1df00 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1df10 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1df20 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1df30 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1df40 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1df50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1df60 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1df70 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1df80 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1df90 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1dfa0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1dfb0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1dfc0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1dfd0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1dfe0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1dff0 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1e000 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e010 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1e020 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1e030 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1e040 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1e050 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1e060 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1e070 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1e080 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1e090 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1e0a0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1e0b0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1e0c0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1e0d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1e0e0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1e0f0 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1e100 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1e110 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1e120 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1e130 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1e140 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1e150 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1e160 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1e170 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1e180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e190 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1e1a0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1e1b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1e1c0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1e1d0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1e1e0 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1e1f0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1e200 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1e210 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1e220 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1e230 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1e240 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1e250 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1e260 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1e270 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1e280 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1e290 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1e2a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1e2b0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1e2c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1e2d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1e2e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e2f0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1e300 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1e310 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1e320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e330 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1e340 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1e350 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1e360 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1e370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e380 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1e390 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1e3a0 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1e3b0 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1e3c0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1e3d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1e3e0 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1e3f0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1e400 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1e410 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1e420 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1e430 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1e440 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1e450 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1e460 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1e470 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1e480 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1e490 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e4a0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1e4b0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1e4c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e4d0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1e4e0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1e4f0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1e500 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1e510 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1e520 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1e530 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1e540 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1e550 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1e560 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1e570 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1e580 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e590 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1e5a0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1e5b0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1e5c0 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
1e5d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e5e0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
1e5f0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
1e600 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1e610 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e620 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1e630 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
1e640 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
1e650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e660 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
1e670 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
1e680 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1e690 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1e6a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e6b0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
1e6c0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
1e6d0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
1e6e0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
1e6f0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
1e700 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
1e710 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
1e720 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
1e730 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
1e740 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
1e750 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e760 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1e770 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
1e780 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1e790 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1e7a0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1e7b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
1e7c0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
1e7d0 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
1e7e0 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a   | return code].
1e7f0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ** from the [sql
1e800 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1e810 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1e820 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1e830 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1e840 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1e850 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1e860 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1e870 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1e880 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1e890 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1e8a0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1e8b0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1e8c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1e8d0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1e8e0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1e8f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e900 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1e910 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1e920 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e930 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1e940 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1e950 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1e960 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1e970 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1e980 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e990 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1e9a0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1e9b0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1e9c0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1e9d0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1e9e0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1e9f0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1ea00 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1ea10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ea20 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1ea30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1ea40 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1ea50 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1ea60 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1ea70 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1ea80 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1ea90 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1eaa0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1eab0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1eac0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1ead0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1eae0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1eaf0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1eb00 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1eb10 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1eb20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1eb30 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1eb40 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1eb50 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eb60 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1eb70 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1eb80 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1eb90 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1eba0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1ebb0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1ebc0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1ebd0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1ebe0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1ebf0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1ec00 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1ec10 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1ec20 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1ec30 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1ec40 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1ec50 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1ec60 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1ec70 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1ec80 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1ec90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1eca0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1ecb0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1ecc0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1ecd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ece0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1ecf0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1ed00 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1ed10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ed20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ed30 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1ed40 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1ed50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ed60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ed70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ed80 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1ed90 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1eda0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1edb0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1edc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1edd0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1ede0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1edf0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1ee00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ee10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ee20 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1ee30 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1ee40 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1ee50 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ee60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ee70 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1ee80 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1ee90 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1eea0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1eeb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1eec0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1eed0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1eee0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1eef0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ef00 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ef10 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ef20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1ef30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ef40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ef50 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1ef60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1ef70 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ef80 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ef90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1efa0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1efb0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1efc0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1efd0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1efe0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eff0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1f000 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1f010 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f020 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f030 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f040 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1f050 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1f060 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f070 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f080 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f090 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1f0a0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1f0b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f0c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f0d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f0e0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1f0f0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1f100 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f110 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f120 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f130 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1f140 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1f150 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f160 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f180 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1f190 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1f1a0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f1b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f1c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f1d0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1f1e0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1f1f0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f200 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f220 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1f230 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1f240 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f250 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1f270 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1f280 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1f290 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1f2a0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1f2b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1f2c0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1f2d0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1f2e0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1f2f0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1f300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1f310 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1f320 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1f330 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1f340 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f350 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1f360 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1f370 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
1f380 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
1f390 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f3a0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1f3b0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1f3c0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1f3d0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f3e0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f3f0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1f400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f410 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1f420 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f430 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f440 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1f450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1f460 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1f470 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1f480 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f490 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1f4a0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1f4b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1f4c0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1f4d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f4e0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1f4f0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1f500 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f510 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f520 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f530 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1f540 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1f550 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f560 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f570 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f580 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1f590 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1f5a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f5b0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1f5c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f5d0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1f5e0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1f5f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f600 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1f610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f620 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1f630 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1f640 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f650 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1f660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f670 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
1f680 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
1f690 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
1f6a0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
1f6b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f6c0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
1f6d0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
1f6e0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
1f6f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1f700 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
1f710 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
1f720 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1f730 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
1f740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f750 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1f760 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1f770 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1f780 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1f790 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1f7a0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1f7b0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1f7c0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1f7d0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1f7e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1f7f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1f800 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1f810 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1f820 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1f830 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1f840 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1f850 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1f860 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1f870 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f880 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1f890 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1f8a0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1f8b0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1f8c0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1f8d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1f8e0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1f8f0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1f900 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1f910 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1f920 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1f930 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1f940 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1f950 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1f960 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1f970 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1f980 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1f990 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1f9a0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1f9b0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1f9c0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
1f9d0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
1f9e0 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
1f9f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
1fa00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
1fa10 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
1fa20 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
1fa30 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
1fa40 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
1fa50 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
1fa60 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
1fa70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1fa80 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1fa90 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1faa0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1fab0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1fac0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1fad0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1fae0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1faf0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1fb00 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1fb10 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1fb20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1fb30 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1fb40 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1fb50 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1fb60 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1fb70 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1fb80 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1fb90 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1fba0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1fbb0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1fbc0 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1fbd0 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1fbe0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1fbf0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1fc00 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1fc10 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1fc20 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1fc30 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1fc40 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1fc50 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1fc60 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1fc70 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1fc80 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1fc90 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1fca0 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1fcb0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1fcc0 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1fcd0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1fce0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1fcf0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
1fd00 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
1fd10 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
1fd20 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
1fd30 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
1fd40 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
1fd50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1fd60 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1fd70 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1fd80 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1fd90 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1fda0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1fdb0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1fdc0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1fdd0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1fde0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1fdf0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1fe00 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1fe10 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1fe20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1fe30 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1fe40 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1fe50 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1fe60 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1fe70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1fe80 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1fe90 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1fea0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1feb0 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1fec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1fed0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1fee0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1fef0 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1ff00 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1ff10 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1ff20 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1ff30 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1ff40 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1ff50 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1ff60 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1ff70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ff80 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1ff90 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
1ffa0 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
1ffb0 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
1ffc0 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
1ffd0 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
1ffe0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
1fff0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
20000 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
20010 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
20020 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
20030 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
20040 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
20050 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
20060 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
20070 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
20080 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
20090 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
200a0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
200b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
200c0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
200d0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
200e0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
200f0 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
20100 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
20110 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
20120 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20130 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
20140 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
20150 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
20160 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
20170 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
20180 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
20190 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
201a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
201b0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
201c0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
201d0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
201e0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
201f0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
20200 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
20210 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
20220 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
20230 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
20240 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
20250 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
20260 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
20270 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
20280 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20290 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
202a0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
202b0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
202c0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
202d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
202e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
202f0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20300 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20310 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
20320 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
20330 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
20340 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20350 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
20360 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
20370 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
20380 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
20390 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
203a0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
203b0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
203c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
203d0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
203e0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
203f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
20400 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
20410 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
20420 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
20430 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
20440 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
20450 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
20460 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
20470 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20480 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
20490 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
204a0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
204b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
204c0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
204d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
204e0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
204f0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
20500 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
20510 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
20520 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
20530 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
20540 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
20550 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
20560 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
20570 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
20580 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
20590 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
205a0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
205b0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
205c0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
205d0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
205e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
205f0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
20600 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
20610 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
20620 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
20630 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
20640 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
20650 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
20660 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
20670 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
20680 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
20690 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
206a0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
206b0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
206c0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
206d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
206e0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
206f0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
20700 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
20710 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
20720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
20730 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
20740 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
20750 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
20760 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20770 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
20780 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
20790 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
207a0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
207b0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
207c0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
207d0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
207e0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
207f0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
20800 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
20810 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
20820 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
20830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20840 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
20850 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
20860 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
20870 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
20880 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
20890 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
208a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
208b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
208c0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
208d0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
208e0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
208f0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
20900 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
20910 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
20920 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
20930 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
20940 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
20950 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
20960 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
20970 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20980 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
20990 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
209a0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
209b0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
209c0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
209d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
209e0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
209f0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
20a00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20a10 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
20a20 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
20a30 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
20a40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
20a50 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
20a60 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
20a70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20a80 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
20a90 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20aa0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
20ab0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
20ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
20ad0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
20ae0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
20af0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
20b00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
20b10 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
20b20 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
20b30 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20b40 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20b50 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
20b60 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
20b70 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
20b80 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
20b90 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
20ba0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
20bb0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
20bc0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
20bd0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
20be0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
20bf0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
20c00 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
20c10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
20c20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
20c30 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
20c40 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
20c50 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
20c60 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20c70 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
20c80 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
20c90 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
20ca0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
20cb0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
20cc0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
20cd0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
20ce0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
20cf0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
20d00 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
20d10 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
20d20 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
20d30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
20d40 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
20d50 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
20d60 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
20d70 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
20d80 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
20d90 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
20da0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20db0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
20dc0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
20dd0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
20de0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
20df0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
20e00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
20e10 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
20e20 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
20e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20e40 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
20e50 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
20e60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
20e70 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
20e80 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
20e90 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
20ea0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
20eb0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
20ec0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
20ed0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
20ee0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
20ef0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
20f00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20f10 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
20f20 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
20f30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
20f40 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
20f50 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
20f60 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
20f70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
20f80 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
20f90 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
20fa0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
20fb0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
20fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20fd0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
20fe0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
20ff0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
21000 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
21010 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
21020 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
21030 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
21040 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
21050 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
21060 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
21070 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21080 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
21090 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
210a0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
210b0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
210c0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
210d0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
210e0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
210f0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
21100 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21110 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
21120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
21130 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
21140 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
21150 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
21160 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
21170 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
21180 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
21190 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
211a0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
211b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
211c0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
211d0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
211e0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
211f0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21200 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
21210 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
21220 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
21230 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
21240 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
21250 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
21260 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
21270 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
21280 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
21290 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
212a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
212b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
212c0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
212d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
212e0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
212f0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
21300 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
21310 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
21320 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
21330 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
21340 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
21350 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
21360 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
21370 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
21380 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
21390 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
213a0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
213b0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
213c0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
213d0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
213e0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
213f0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
21400 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
21410 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
21420 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
21430 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
21440 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
21450 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
21460 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
21470 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
21480 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
21490 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
214a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
214b0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
214c0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
214d0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
214e0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
214f0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
21500 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
21510 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
21520 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
21530 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
21540 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
21550 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
21560 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
21570 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
21580 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
21590 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
215a0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
215b0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
215c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
215d0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
215e0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
215f0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
21600 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
21610 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
21620 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
21630 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
21640 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
21650 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
21660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
21670 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
21680 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
21690 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
216a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
216b0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
216c0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
216d0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
216e0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
216f0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
21700 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
21710 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
21720 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
21730 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
21740 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
21750 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
21760 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
21770 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
21780 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
21790 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
217a0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
217b0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
217c0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
217d0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
217e0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
217f0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
21800 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
21810 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
21820 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
21830 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
21840 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
21850 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
21860 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
21870 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
21880 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
21890 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
218a0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
218b0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
218c0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
218d0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
218e0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
218f0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
21900 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
21910 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
21920 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
21930 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
21940 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
21950 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
21960 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
21970 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
21980 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
21990 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
219a0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
219b0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
219c0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
219d0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
219e0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
219f0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
21a00 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
21a10 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
21a20 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
21a30 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
21a40 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
21a50 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
21a60 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
21a70 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
21a80 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
21a90 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
21aa0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
21ab0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
21ac0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
21ad0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
21ae0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
21af0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
21b00 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
21b10 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
21b20 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
21b30 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
21b40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
21b50 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
21b60 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
21b70 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
21b80 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
21b90 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
21ba0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
21bb0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
21bc0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
21bd0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
21be0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
21bf0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
21c00 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
21c10 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
21c20 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
21c30 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
21c40 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
21c50 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
21c60 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
21c70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
21c80 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
21c90 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
21ca0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
21cb0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
21cc0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
21cd0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
21ce0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
21cf0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
21d00 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
21d10 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
21d20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
21d30 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
21d40 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
21d50 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
21d60 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
21d70 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
21d80 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21d90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21da0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
21db0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
21dc0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
21dd0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
21de0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
21df0 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
21e00 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
21e10 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
21e20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
21e30 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
21e40 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
21e50 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
21e60 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
21e70 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
21e80 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
21e90 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
21ea0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
21eb0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
21ec0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
21ed0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
21ee0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
21ef0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
21f00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
21f10 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
21f20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
21f30 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
21f40 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
21f50 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21f60 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
21f70 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
21f80 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
21f90 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
21fa0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
21fb0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
21fc0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
21fd0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
21fe0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
21ff0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
22000 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
22010 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
22020 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
22030 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
22040 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
22050 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
22060 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
22070 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
22080 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
22090 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
220a0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
220b0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
220c0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
220d0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
220e0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
220f0 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
22100 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
22110 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
22120 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
22130 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
22140 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
22150 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
22160 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22170 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22180 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
22190 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
221a0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
221b0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
221c0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
221d0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
221e0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
221f0 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
22200 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
22210 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
22220 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22230 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
22240 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
22250 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
22260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22270 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
22280 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
22290 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
222a0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
222b0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
222c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
222d0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
222e0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
222f0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
22300 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
22310 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
22320 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
22330 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
22340 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
22350 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
22360 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
22370 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
22380 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22390 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
223a0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
223b0 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
223c0 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
223d0 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
223e0 65 74 65 72 20 6d 61 79 20 62 65 20 22 74 72 75  eter may be "tru
223f0 65 22 20 28 6f 72 20 22 6f 6e 22 20 6f 72 20 22  e" (or "on" or "
22400 79 65 73 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  yes" or.**     "
22410 31 22 29 20 6f 72 20 22 66 61 6c 73 65 22 20 28  1") or "false" (
22420 6f 72 20 22 6f 66 66 22 20 6f 72 20 22 6e 6f 22  or "off" or "no"
22430 20 6f 72 20 22 30 22 29 20 74 6f 20 69 6e 64 69   or "0") to indi
22440 63 61 74 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  cate that the.**
22450 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
22460 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
22470 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
22480 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
22490 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
224a0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
224b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
224c0 65 20 72 65 73 69 64 65 73 2e 20 20 5e 54 68 65  e resides.  ^The
224d0 20 70 73 6f 77 20 71 75 65 72 79 0a 2a 2a 20 20   psow query.**  
224e0 20 20 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 6c     parameter onl
224f0 79 20 77 6f 72 6b 73 20 66 6f 72 20 74 68 65 20  y works for the 
22500 62 75 69 6c 74 2d 69 6e 20 75 6e 69 78 20 61 6e  built-in unix an
22510 64 20 57 69 6e 64 6f 77 73 20 56 46 53 65 73 2e  d Windows VFSes.
22520 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
22530 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
22540 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
22550 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
22560 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
22570 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
22580 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
22590 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
225a0 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
225b0 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
225c0 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
225d0 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
225e0 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
225f0 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
22600 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
22610 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
22620 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
22630 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
22640 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
22650 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
22660 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
22670 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
22680 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
22690 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
226a0 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
226b0 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
226c0 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
226d0 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
226e0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
226f0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
22700 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
22710 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
22720 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
22730 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
22740 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
22750 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
22760 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
22770 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
22780 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
22790 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
227a0 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
227b0 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
227c0 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
227d0 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
227e0 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
227f0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22800 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
22810 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
22820 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
22830 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
22840 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
22850 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
22860 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
22870 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
22880 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
22890 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
228a0 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
228b0 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
228c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
228d0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
228e0 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
228f0 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
22900 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
22910 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
22920 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
22930 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
22940 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
22950 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
22960 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
22970 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
22980 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
22990 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
229a0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
229b0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
229c0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
229d0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
229e0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
229f0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
22a00 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
22a10 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
22a20 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
22a30 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
22a40 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
22a50 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
22a60 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
22a70 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
22a80 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
22a90 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
22aa0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
22ab0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
22ac0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
22ad0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
22ae0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
22af0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
22b00 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
22b10 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
22b20 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
22b30 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
22b40 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
22b50 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
22b60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22b70 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
22b80 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
22b90 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
22ba0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
22bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22bc0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
22bd0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
22be0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
22bf0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
22c00 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
22c10 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
22c20 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
22c30 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
22c40 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
22c50 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
22c60 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
22c70 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
22c80 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
22c90 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
22ca0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
22cb0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
22cc0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
22cd0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
22ce0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
22cf0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
22d00 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
22d10 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
22d20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
22d30 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
22d40 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
22d50 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
22d60 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
22d70 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
22d80 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
22d90 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
22da0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
22db0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
22dc0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
22dd0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
22de0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
22df0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
22e00 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
22e10 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
22e20 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
22e30 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
22e40 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
22e50 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
22e60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
22e70 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
22e80 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
22e90 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
22ea0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
22eb0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
22ec0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
22ed0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
22ee0 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
22ef0 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
22f00 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
22f10 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
22f20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
22f30 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
22f40 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
22f50 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
22f60 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
22f70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
22f80 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
22f90 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
22fa0 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
22fb0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22fc0 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
22fd0 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
22fe0 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
22ff0 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
23000 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
23010 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
23020 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
23030 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
23040 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
23050 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
23060 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
23070 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
23080 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
23090 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
230a0 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
230b0 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
230c0 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
230d0 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
230e0 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
230f0 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
23100 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
23110 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
23120 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
23130 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
23140 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
23150 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
23160 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
23170 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
23180 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
23190 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
231a0 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
231b0 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
231c0 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
231d0 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
231e0 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
231f0 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
23200 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
23210 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
23220 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
23230 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
23240 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
23250 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
23260 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
23270 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
23280 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
23290 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
232a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
232b0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
232c0 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
232d0 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
232e0 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
232f0 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
23300 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
23310 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
23320 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
23330 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
23340 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
23350 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
23360 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
23370 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
23380 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
23390 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
233a0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
233b0 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
233c0 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
233d0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
233e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
233f0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23400 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
23410 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
23420 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
23430 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
23440 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
23450 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
23460 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
23470 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
23480 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23490 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
234a0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
234b0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
234c0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
234d0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
234e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
234f0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23500 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
23510 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
23520 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
23530 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23540 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23550 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
23560 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
23570 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23580 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
235a0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
235b0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
235c0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
235d0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
235e0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
235f0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
23600 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23610 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
23620 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
23630 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
23640 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
23650 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
23660 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
23670 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
23680 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
23690 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
236a0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
236b0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
236c0 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
236d0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
236e0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
236f0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
23700 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
23710 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
23720 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
23730 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
23740 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
23750 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
23760 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
23770 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23780 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
23790 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
237a0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
237b0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
237c0 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
237d0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
237e0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
237f0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
23800 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
23810 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
23820 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
23830 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
23840 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
23850 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
23860 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
23870 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
23880 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
23890 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
238a0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
238b0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
238c0 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
238d0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
238e0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
238f0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
23900 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
23910 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23920 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
23930 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
23940 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
23950 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
23960 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
23970 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
23980 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
23990 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
239a0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
239b0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
239c0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
239d0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
239e0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
239f0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
23a00 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
23a10 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
23a20 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
23a30 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
23a40 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
23a50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23a60 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
23a70 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
23a80 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
23a90 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
23aa0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
23ab0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
23ac0 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
23ad0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
23ae0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
23af0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
23b00 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
23b10 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23b20 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
23b30 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
23b40 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
23b50 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23b60 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
23b70 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
23b80 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
23b90 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
23ba0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
23bb0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
23bc0 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
23bd0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
23be0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
23bf0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
23c00 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
23c10 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
23c20 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
23c30 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23c40 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
23c50 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
23c60 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
23c70 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
23c80 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
23c90 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
23ca0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
23cb0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
23cc0 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
23cd0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
23ce0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
23cf0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
23d00 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
23d10 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
23d20 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
23d30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
23d40 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
23d50 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
23d60 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
23d70 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23d80 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
23d90 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23da0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
23db0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
23dc0 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
23dd0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
23de0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
23df0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
23e00 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
23e10 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
23e20 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
23e30 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
23e40 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
23e50 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
23e60 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
23e70 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
23e80 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
23e90 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23ea0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
23eb0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
23ec0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
23ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
23ee0 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
23ef0 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
23f00 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
23f10 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
23f20 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
23f30 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
23f40 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
23f50 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
23f60 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
23f70 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
23f80 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
23f90 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
23fa0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
23fb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23fc0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
23fd0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
23fe0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
23ff0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
24000 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
24010 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
24020 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
24030 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
24040 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24050 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
24060 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
24070 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
24080 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
24090 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
240a0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
240b0 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
240c0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
240d0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
240e0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
240f0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
24100 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
24110 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
24120 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
24130 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
24140 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
24150 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
24160 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
24170 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
24180 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
24190 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
241a0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
241b0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
241c0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
241d0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
241e0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
241f0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
24200 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
24210 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
24220 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
24230 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
24240 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
24250 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
24260 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
24270 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
24280 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
24290 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
242a0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
242b0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
242c0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
242d0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
242e0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
242f0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
24300 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
24310 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
24320 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
24330 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24340 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
24350 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
24360 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
24370 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
24380 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
24390 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
243a0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
243b0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
243c0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
243d0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
243e0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
243f0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
24400 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
24410 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
24420 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
24430 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
24440 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
24450 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
24460 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
24470 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
24480 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
24490 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
244a0 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
244b0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
244c0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
244d0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
244e0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
244f0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
24500 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
24510 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
24520 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
24530 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
24540 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
24550 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
24560 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
24570 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
24580 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24590 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
245a0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
245b0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
245c0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
245d0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
245e0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
245f0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
24600 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
24610 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
24620 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
24630 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
24640 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
24650 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
24660 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
24670 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
24680 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
24690 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
246a0 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
246b0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
246c0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
246d0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
246e0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
246f0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
24700 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
24710 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
24720 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
24730 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
24740 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
24750 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24760 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
24770 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
24780 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
24790 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
247a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
247b0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
247c0 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
247d0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
247e0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
247f0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
24800 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
24810 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
24820 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
24830 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24840 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
24850 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
24860 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
24870 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
24880 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
24890 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
248a0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
248b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
248c0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
248d0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
248e0 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
248f0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
24900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
24910 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
24920 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
24930 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
24940 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
24950 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
24960 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
24970 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24980 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
24990 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
249a0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
249b0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
249c0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
249d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
249e0 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
249f0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
24a00 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
24a10 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
24a20 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
24a30 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
24a40 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
24a50 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
24a60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24a70 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
24a80 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
24a90 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
24aa0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
24ab0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
24ac0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
24ad0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24ae0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
24af0 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
24b00 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
24b10 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
24b20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
24b30 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
24b40 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
24b50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
24b60 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
24b70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24b80 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
24b90 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
24ba0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
24bb0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
24bc0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
24bd0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
24be0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
24bf0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
24c00 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
24c10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24c20 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
24c30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
24c40 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
24c50 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
24c60 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
24c70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
24c80 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
24c90 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
24ca0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
24cb0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
24cc0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
24cd0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
24ce0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
24cf0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
24d00 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
24d10 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
24d20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
24d30 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
24d40 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
24d50 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
24d60 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
24d70 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
24d80 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
24d90 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
24da0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
24db0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
24dc0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24dd0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
24de0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
24df0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
24e00 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
24e10 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
24e20 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
24e30 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
24e40 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
24e50 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
24e60 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
24e70 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
24e80 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
24e90 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
24ea0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
24eb0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
24ec0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
24ed0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
24ee0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
24ef0 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
24f00 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
24f10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
24f20 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
24f30 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
24f40 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
24f50 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
24f60 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
24f70 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
24f80 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
24f90 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
24fa0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
24fb0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24fc0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
24fd0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
24fe0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
24ff0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
25000 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
25010 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
25020 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
25030 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
25040 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
25050 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
25060 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
25070 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
25080 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
25090 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
250a0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
250b0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
250c0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
250d0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
250e0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
250f0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
25100 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
25110 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
25120 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
25130 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
25140 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
25150 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
25160 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
25170 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
25180 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
25190 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
251a0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
251b0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
251c0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
251d0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
251e0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
251f0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
25200 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
25210 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
25220 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
25230 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
25240 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
25250 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
25260 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
25270 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
25280 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
25290 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
252a0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
252b0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
252c0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
252d0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
252e0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
252f0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
25300 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
25310 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
25320 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
25330 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
25340 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
25350 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
25360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25370 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
25380 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
25390 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
253a0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
253b0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
253c0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
253d0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
253e0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
253f0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
25400 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
25410 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
25420 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
25430 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
25440 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
25450 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
25460 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
25470 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
25480 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
25490 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
254a0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
254b0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
254c0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
254d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
254e0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
254f0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
25500 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25510 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
25520 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
25530 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
25540 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
25550 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25560 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
25570 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25580 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
25590 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
255a0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
255b0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
255c0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
255d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
255e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
255f0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25600 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
25610 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25620 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
25630 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
25640 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
25650 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
25660 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
25670 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
25680 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
25690 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
256a0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
256b0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
256c0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
256d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
256e0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
256f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25700 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
25710 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25720 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
25730 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
25740 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
25750 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
25760 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
25770 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
25780 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25790 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
257a0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
257b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
257c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
257d0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
257e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
257f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25800 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
25810 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25820 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
25830 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25840 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
25850 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
25860 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
25870 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
25880 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
25890 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
258a0 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
258b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
258c0 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
258d0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
258e0 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
258f0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
25900 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
25910 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25920 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
25930 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
25940 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
25950 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
25960 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25970 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
25980 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
25990 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
259a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
259b0 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
259c0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
259d0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
259e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
259f0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
25a00 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
25a10 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
25a20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25a30 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
25a40 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
25a50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
25a60 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
25a70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25a80 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
25a90 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
25aa0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
25ab0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
25ac0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
25ad0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25ae0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
25af0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
25b00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25b10 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25b20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25b30 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
25b40 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
25b50 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
25b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
25b70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25b80 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
25b90 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
25ba0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25bb0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
25bc0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
25bd0 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
25be0 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
25bf0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
25c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25c10 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
25c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25c30 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
25c40 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
25c50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
25c60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
25c70 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
25c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25c90 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
25ca0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25cb0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
25cc0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
25cd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25ce0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
25cf0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
25d00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
25d10 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
25d20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
25d30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
25d40 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
25d50 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
25d60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
25d70 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
25d80 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
25d90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
25da0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
25db0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
25dc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25dd0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
25de0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
25df0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25e00 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
25e10 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
25e20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
25e30 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
25e40 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
25e50 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
25e60 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
25e70 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
25e80 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
25e90 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
25ea0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
25eb0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
25ec0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
25ed0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
25ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25ef0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
25f00 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
25f10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
25f20 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
25f30 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
25f40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25f50 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
25f60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
25f70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
25f80 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
25f90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25fa0 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
25fb0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
25fc0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
25fd0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
25fe0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
25ff0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
26000 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
26010 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
26020 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
26030 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
26040 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26050 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
26060 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
26070 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26080 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
26090 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
260a0 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
260b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
260c0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
260d0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
260e0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
260f0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
26100 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
26110 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
26120 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
26130 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
26140 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
26150 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
26160 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
26170 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
26180 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
26190 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
261a0 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
261b0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
261c0 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
261d0 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
261e0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
261f0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
26200 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
26210 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
26220 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
26230 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
26240 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
26250 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
26260 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
26270 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
26280 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
26290 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
262a0 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
262b0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
262c0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
262d0 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
262e0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
262f0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
26300 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
26310 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
26320 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
26330 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
26340 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
26350 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
26360 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
26370 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
26380 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
26390 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
263a0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
263b0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
263c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
263d0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
263e0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
263f0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
26400 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
26410 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
26420 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
26430 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
26440 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
26450 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
26460 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
26470 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
26480 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
26490 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
264a0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
264b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
264c0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
264d0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
264e0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
264f0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
26500 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
26510 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
26520 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
26530 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
26540 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
26550 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
26560 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
26570 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
26580 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
26590 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
265a0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
265b0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
265c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
265d0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
265e0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
265f0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
26600 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
26610 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
26620 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26630 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
26640 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
26650 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
26660 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
26670 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
26680 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
26690 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
266a0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
266b0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
266c0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
266d0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
266e0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
266f0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
26700 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
26710 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
26720 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
26730 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
26740 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
26750 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
26760 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
26770 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
26780 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
26790 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
267a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
267b0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
267c0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
267d0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
267e0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
267f0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
26800 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
26810 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
26820 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
26830 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
26840 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
26850 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
26860 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
26870 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
26880 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
26890 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
268a0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
268b0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
268c0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
268d0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
268e0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
268f0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
26900 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
26910 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
26920 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
26930 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
26940 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
26950 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26960 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
26970 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
26980 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
26990 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
269a0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
269b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
269c0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
269d0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
269e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
269f0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
26a00 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
26a10 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
26a20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
26a30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
26a40 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
26a50 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
26a60 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
26a70 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
26a80 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
26a90 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
26aa0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
26ab0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26ac0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
26ad0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
26ae0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
26af0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
26b00 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
26b10 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
26b20 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
26b30 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
26b40 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
26b50 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
26b60 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
26b70 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
26b80 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
26b90 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
26ba0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
26bb0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
26bc0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
26bd0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
26be0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
26bf0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
26c00 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
26c10 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
26c20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
26c30 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
26c40 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
26c50 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
26c60 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
26c70 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
26c80 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
26c90 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
26ca0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
26cb0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
26cc0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
26cd0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
26ce0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
26cf0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
26d00 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
26d10 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
26d20 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
26d30 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
26d40 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
26d50 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
26d60 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
26d70 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
26d80 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
26d90 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
26da0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
26db0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
26dc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
26dd0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
26de0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
26df0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
26e00 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
26e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26e20 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
26e30 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26e40 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26e50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26e60 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
26e70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26e80 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
26e90 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
26ea0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
26eb0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26ec0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
26ed0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
26ee0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26ef0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26f00 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26f10 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
26f20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
26f30 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
26f40 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
26f50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
26f60 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
26f70 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26f80 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
26f90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26fa0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
26fb0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
26fc0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
26fd0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
26fe0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
26ff0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27000 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
27010 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
27020 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27030 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
27040 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
27050 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
27060 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
27070 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
27080 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
27090 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
270a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
270b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
270c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
270d0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
270e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
270f0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27100 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27110 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
27120 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
27130 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
27140 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
27150 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
27160 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
27170 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
27180 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27190 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
271a0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
271b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
271c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
271d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
271e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
271f0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
27200 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
27210 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
27220 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27230 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
27240 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
27250 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
27260 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
27270 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
27280 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
27290 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
272a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
272b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
272c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
272d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
272e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
272f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
27300 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
27310 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
27320 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
27330 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
27340 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
27350 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
27360 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
27370 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
27380 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
27390 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
273a0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
273b0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
273c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
273d0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
273e0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
273f0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
27400 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27410 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
27420 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
27430 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
27440 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
27450 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27470 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
27480 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
27490 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
274a0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
274b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
274c0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
274d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
274e0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
274f0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
27500 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27510 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
27520 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
27530 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
27540 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
27550 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
27560 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
27570 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27580 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
27590 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
275a0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
275b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
275c0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
275d0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
275e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
275f0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
27600 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
27610 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
27620 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
27630 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
27640 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
27650 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
27660 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
27670 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27680 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
27690 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
276a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
276b0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
276c0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
276d0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
276e0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
276f0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
27700 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
27710 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
27720 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
27730 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
27740 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
27750 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27760 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
27770 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
27780 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
27790 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
277a0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
277b0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
277c0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
277d0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
277e0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
277f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27800 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
27810 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
27820 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
27830 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
27840 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
27850 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
27860 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
27870 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
27880 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
27890 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
278a0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
278b0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
278c0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
278d0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
278e0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
278f0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27900 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
27910 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
27920 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
27930 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
27940 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
27950 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27960 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
27970 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
27980 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
27990 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
279a0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
279b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
279c0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
279d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
279e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
279f0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
27a00 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
27a10 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
27a20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
27a30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
27a40 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
27a50 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
27a60 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
27a70 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27a80 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
27a90 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
27aa0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
27ab0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27ac0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
27ad0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
27ae0 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
27af0 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
27b00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
27b10 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
27b20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
27b30 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
27b40 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
27b50 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
27b60 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
27b70 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
27b80 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
27b90 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
27ba0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
27bb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
27bc0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
27bd0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
27be0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
27bf0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
27c00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
27c10 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
27c20 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
27c30 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
27c40 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
27c50 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
27c60 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
27c70 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
27c80 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
27c90 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
27ca0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
27cb0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
27cc0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
27cd0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
27ce0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
27cf0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
27d00 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
27d10 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
27d20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
27d30 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
27d40 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
27d50 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
27d60 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
27d70 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
27d80 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
27d90 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
27da0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
27db0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
27dc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27dd0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
27de0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
27df0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27e00 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
27e10 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
27e20 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
27e30 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
27e40 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
27e50 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
27e60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
27e70 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
27e80 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
27e90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27ea0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
27eb0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
27ec0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
27ed0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
27ee0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
27ef0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
27f00 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
27f10 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
27f20 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
27f30 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
27f40 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
27f50 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
27f60 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
27f70 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
27f80 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
27f90 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
27fa0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
27fb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
27fc0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
27fd0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
27fe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
27ff0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
28000 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
28010 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
28020 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
28030 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
28040 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
28050 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
28060 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
28070 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
28080 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
28090 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
280a0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
280b0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
280c0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
280d0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
280e0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
280f0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
28100 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28110 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
28120 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
28130 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
28140 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
28150 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
28160 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
28170 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
28180 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
28190 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
281a0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
281b0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
281c0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
281d0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
281e0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
281f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
28200 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
28210 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
28220 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
28230 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
28240 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
28250 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28260 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
28270 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
28280 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
28290 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
282a0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
282b0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
282c0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
282d0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
282e0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
282f0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
28300 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
28310 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
28320 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
28330 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
28340 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
28350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28360 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28370 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
28380 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
28390 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
283a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
283b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
283c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
283d0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
283e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
283f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
28400 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
28410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
28420 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
28430 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
28440 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28450 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
28460 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
28470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
28480 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
28490 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
284a0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
284b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
284c0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
284d0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
284e0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
284f0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
28500 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28510 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
28520 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
28530 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
28540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28550 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
28560 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
28570 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
28580 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
28590 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
285a0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
285b0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
285c0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
285d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
285e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
285f0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
28600 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
28610 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
28620 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
28630 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
28640 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
28650 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28660 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
28670 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
28680 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
28690 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
286a0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
286b0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
286c0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
286d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
286e0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
286f0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
28700 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28710 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
28720 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
28730 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
28740 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
28750 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
28760 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
28770 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
28780 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
28790 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
287a0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
287b0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
287c0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
287d0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
287e0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
287f0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
28800 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
28810 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
28820 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
28830 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
28840 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
28850 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
28860 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
28870 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
28880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28890 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
288a0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
288b0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
288c0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
288d0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
288e0 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
288f0 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
28900 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
28910 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
28920 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
28930 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
28940 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
28950 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
28960 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
28970 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
28980 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
28990 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
289a0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
289b0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
289c0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
289d0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
289e0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
289f0 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
28a00 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
28a10 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
28a20 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
28a30 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
28a40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
28a50 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
28a60 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
28a70 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
28a80 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
28a90 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
28aa0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
28ab0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
28ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
28ad0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
28ae0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
28af0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28b00 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
28b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
28b20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
28b30 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
28b40 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
28b50 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
28b60 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
28b70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
28b80 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
28b90 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
28ba0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
28bb0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
28bc0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
28bd0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
28be0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
28bf0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
28c00 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
28c10 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
28c20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
28c30 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
28c40 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
28c50 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
28c60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28c70 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
28c80 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
28c90 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
28ca0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
28cb0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
28cc0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
28cd0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
28ce0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
28cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
28d00 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
28d10 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
28d20 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
28d30 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
28d40 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
28d50 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
28d60 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
28d70 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
28d80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
28d90 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
28da0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28db0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
28dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28dd0 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
28de0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
28df0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
28e00 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
28e10 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
28e20 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
28e30 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
28e40 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
28e50 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
28e60 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
28e70 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
28e80 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
28e90 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
28ea0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
28eb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
28ec0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
28ed0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
28ee0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
28ef0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
28f00 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
28f10 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
28f20 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
28f30 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
28f40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28f50 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28f60 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
28f70 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
28f80 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
28f90 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
28fa0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
28fb0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
28fc0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
28fd0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
28fe0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
28ff0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29000 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
29010 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
29020 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
29030 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
29040 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
29050 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
29060 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29070 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
29080 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29090 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
290a0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
290b0 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
290c0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
290d0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
290e0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
290f0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
29100 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
29110 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
29120 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
29130 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
29140 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
29150 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
29160 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
29170 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
29180 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
29190 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
291a0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
291b0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
291c0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
291d0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
291e0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
291f0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
29200 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
29210 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
29220 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
29230 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
29240 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
29250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29260 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
29270 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
29280 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
29290 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
292a0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
292b0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
292c0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
292d0 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
292e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
292f0 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
29300 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
29310 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
29320 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
29330 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29340 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
29350 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
29360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29370 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
29380 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
29390 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
293a0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
293b0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
293c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
293d0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
293e0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
293f0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
29400 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
29410 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
29420 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
29430 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
29440 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
29450 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
29460 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
29470 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
29480 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
29490 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
294a0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
294b0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
294c0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
294d0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
294e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
294f0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
29500 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
29510 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
29520 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
29530 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
29540 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
29550 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
29560 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
29570 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
29580 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
29590 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
295a0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
295b0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
295c0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
295d0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
295e0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
295f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
29600 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
29610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
29620 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
29630 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
29640 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
29650 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
29660 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
29670 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
29680 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
29690 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
296a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
296b0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
296c0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
296d0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
296e0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
296f0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
29700 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
29710 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
29720 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
29730 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
29740 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
29750 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
29760 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
29770 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
29780 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
29790 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
297a0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
297b0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
297c0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
297d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
297e0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
297f0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
29800 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
29810 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
29820 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
29830 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
29840 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
29850 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29860 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
29870 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
29880 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
29890 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
298a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
298b0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
298c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
298d0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
298e0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
298f0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
29900 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
29910 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
29920 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
29930 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
29940 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
29950 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
29960 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
29970 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
29980 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
29990 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
299a0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
299b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
299c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
299d0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
299e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
299f0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29a00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
29a10 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
29a20 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
29a30 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
29a40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29a50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29a60 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
29a70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
29a80 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
29a90 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
29aa0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
29ab0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
29ac0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
29ad0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29ae0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
29af0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29b00 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
29b10 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
29b20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29b30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29b40 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
29b50 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
29b60 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
29b70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29b80 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29b90 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
29ba0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
29bb0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
29bc0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
29bd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29be0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
29bf0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
29c00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
29c10 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
29c20 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
29c30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29c40 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
29c50 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
29c60 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
29c70 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
29c80 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
29c90 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
29ca0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
29cb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
29cc0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
29cd0 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
29ce0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
29cf0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
29d00 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
29d10 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
29d20 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
29d30 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
29d40 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
29d50 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
29d60 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
29d70 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
29d80 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
29d90 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
29da0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
29db0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
29dc0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
29dd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
29de0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
29df0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
29e00 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
29e10 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
29e20 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
29e30 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
29e40 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
29e50 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
29e60 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
29e70 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
29e80 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
29e90 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
29ea0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
29eb0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
29ec0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29ed0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
29ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29ef0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29f00 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
29f10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29f20 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
29f30 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
29f40 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
29f50 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
29f60 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
29f70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29f80 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
29f90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
29fa0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
29fb0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
29fc0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
29fd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29fe0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
29ff0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2a000 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2a010 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2a020 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2a030 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2a040 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2a050 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2a060 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2a070 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2a080 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2a090 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2a0a0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2a0b0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2a0c0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2a0d0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2a0e0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2a0f0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2a100 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2a110 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2a120 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2a130 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2a140 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2a150 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2a160 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2a170 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2a180 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2a190 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2a1a0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2a1b0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2a1c0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2a1d0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2a1e0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2a1f0 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2a200 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2a210 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2a220 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2a230 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2a240 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2a250 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2a260 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2a270 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2a280 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2a290 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2a2a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a2b0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2a2c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a2d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a2e0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2a2f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a300 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2a310 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2a320 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a330 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a340 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a350 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a360 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2a370 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2a380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2a390 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2a3a0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2a3b0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
2a3c0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2a3d0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2a3e0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2a3f0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2a400 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2a410 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2a420 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2a430 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2a440 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a450 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2a460 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2a470 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2a480 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2a490 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2a4a0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2a4b0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2a4c0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2a4d0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2a4e0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2a4f0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2a500 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2a510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2a520 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2a530 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a540 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a550 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2a560 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a570 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2a580 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2a590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a5a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2a5b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a5c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a5d0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
2a5e0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
2a5f0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
2a600 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2a610 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
2a620 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2a630 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
2a640 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2a650 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2a660 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a670 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2a680 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2a690 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2a6a0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2a6b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2a6c0 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2a6d0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2a6e0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2a6f0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
2a700 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
2a710 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2a720 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2a730 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2a740 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2a750 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2a760 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2a770 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2a780 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2a790 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2a7a0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2a7b0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2a7c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2a7d0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2a7e0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2a7f0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2a800 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2a810 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2a820 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2a830 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a840 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2a850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2a860 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2a870 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2a880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a890 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2a8a0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2a8b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2a8c0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2a8d0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2a8e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2a8f0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2a900 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2a910 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2a920 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2a930 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2a940 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2a950 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a960 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2a970 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2a980 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2a990 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2a9a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2a9b0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2a9c0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2a9d0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2a9e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2a9f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2aa00 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2aa10 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2aa20 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2aa30 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2aa40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2aa50 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2aa60 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2aa70 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2aa80 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2aa90 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2aaa0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2aab0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2aac0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2aad0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2aae0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2aaf0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2ab00 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2ab10 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2ab20 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2ab30 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2ab40 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2ab50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2ab60 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2ab70 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2ab80 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2ab90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2aba0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2abb0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2abc0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2abd0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2abe0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2abf0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2ac00 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2ac10 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2ac20 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2ac30 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2ac40 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2ac50 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2ac60 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2ac70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2ac80 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2ac90 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2aca0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2acb0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2acc0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2acd0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2ace0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2acf0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2ad00 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2ad10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2ad20 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2ad30 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2ad40 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2ad50 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2ad60 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2ad70 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2ad80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2ad90 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2ada0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
2adb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2adc0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2add0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ade0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2adf0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2ae00 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2ae10 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
2ae20 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2ae30 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2ae40 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2ae50 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2ae60 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2ae70 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2ae80 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2ae90 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2aea0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2aeb0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2aec0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2aed0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2aee0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2aef0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2af00 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2af10 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2af20 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2af30 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2af40 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2af50 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2af60 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2af70 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2af80 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2af90 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2afa0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2afb0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2afc0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2afd0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2afe0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2aff0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2b000 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2b010 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b020 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2b030 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2b040 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2b050 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2b060 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2b070 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b080 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2b090 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2b0a0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2b0b0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2b0c0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2b0d0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2b0e0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2b0f0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2b100 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2b110 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2b120 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2b130 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2b140 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2b150 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2b160 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2b170 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2b180 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b190 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2b1a0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2b1b0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2b1c0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2b1d0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2b1e0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2b1f0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2b200 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2b210 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2b220 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2b230 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2b240 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2b250 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2b260 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2b270 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2b280 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2b290 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2b2a0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2b2b0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2b2c0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2b2d0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2b2e0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2b2f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2b300 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2b310 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2b320 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2b330 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2b340 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2b350 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2b360 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2b370 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2b380 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2b390 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2b3a0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2b3b0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2b3c0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2b3d0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2b3e0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2b3f0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2b400 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2b410 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2b420 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2b430 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2b440 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2b450 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2b460 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2b470 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2b480 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2b490 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2b4a0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2b4b0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2b4c0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2b4d0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2b4e0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2b4f0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2b500 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2b510 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2b520 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b530 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2b540 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2b550 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2b560 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2b570 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2b580 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2b590 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2b5a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2b5b0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2b5c0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2b5d0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2b5e0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2b5f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b600 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2b610 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2b620 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2b630 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2b640 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2b650 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b660 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2b670 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2b680 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2b690 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b6a0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2b6b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2b6c0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2b6d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b6e0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2b6f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b700 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2b710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b720 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2b730 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b740 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2b760 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2b770 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2b780 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b790 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2b7a0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2b7b0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2b7c0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2b7d0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2b7e0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2b7f0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2b800 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2b810 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b820 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2b830 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2b840 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2b850 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2b860 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2b870 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2b880 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2b890 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2b8a0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2b8b0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2b8c0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2b8d0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2b8e0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2b8f0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2b900 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2b910 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2b920 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2b930 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2b940 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2b950 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2b960 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2b970 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b980 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2b990 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2b9a0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2b9b0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2b9c0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2b9d0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2b9e0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2b9f0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2ba00 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2ba10 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2ba20 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2ba30 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2ba40 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2ba50 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2ba60 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2ba70 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2ba80 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2ba90 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2baa0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2bab0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2bac0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2bad0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2bae0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2baf0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2bb00 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2bb10 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2bb20 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2bb30 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2bb40 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2bb50 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2bb60 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2bb70 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2bb80 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2bb90 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2bba0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2bbb0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2bbc0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2bbd0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2bbe0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2bbf0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2bc00 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2bc10 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2bc20 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2bc30 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2bc40 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
2bc50 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2bc60 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2bc70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2bc80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2bc90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2bca0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2bcb0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2bcc0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2bcd0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2bce0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2bcf0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2bd00 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2bd10 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2bd20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2bd30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2bd40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2bd50 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2bd60 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2bd70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2bd80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bd90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2bda0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2bdb0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2bdc0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2bdd0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2bde0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2bdf0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2be00 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2be10 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2be20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2be30 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2be40 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2be50 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2be60 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2be70 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2be80 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2be90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bea0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2beb0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bec0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2bed0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2bee0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2bef0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2bf00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2bf10 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2bf20 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2bf30 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2bf40 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2bf50 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2bf60 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2bf70 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2bf80 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2bf90 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2bfa0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2bfb0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2bfc0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2bfd0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2bfe0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2bff0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2c000 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2c010 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2c020 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2c030 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2c040 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2c050 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2c060 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2c070 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2c080 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2c090 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2c0a0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2c0b0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2c0c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2c0d0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2c0e0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2c0f0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2c100 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2c110 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2c120 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c130 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2c140 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2c150 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2c160 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2c170 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2c180 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2c190 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2c1a0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2c1b0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2c1c0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2c1d0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2c1e0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2c1f0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2c200 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2c210 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2c220 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2c230 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2c240 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2c250 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2c260 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2c270 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2c280 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2c290 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2c2a0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2c2b0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2c2c0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2c2d0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2c2e0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2c2f0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2c300 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2c310 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2c320 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2c330 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2c340 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2c350 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2c360 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2c370 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2c380 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2c390 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2c3a0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2c3b0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2c3c0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2c3d0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2c3e0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2c3f0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2c400 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2c410 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2c420 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2c430 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2c440 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2c450 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2c460 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2c470 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2c480 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2c490 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2c4a0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2c4b0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2c4c0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2c4d0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2c4e0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2c4f0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2c500 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2c510 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2c520 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2c530 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2c540 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2c550 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2c560 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2c570 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2c580 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2c590 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2c5a0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2c5b0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2c5c0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2c5d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c5e0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2c5f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2c600 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2c610 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2c620 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2c630 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2c640 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2c650 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2c660 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2c670 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2c680 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2c690 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2c6a0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2c6b0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2c6c0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2c6d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c6e0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2c6f0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2c700 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2c710 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2c720 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2c730 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2c740 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2c750 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2c760 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2c770 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2c780 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2c790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c7a0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2c7b0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2c7c0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2c7d0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2c7e0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2c7f0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2c800 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2c810 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2c820 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2c830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2c840 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2c850 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2c860 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2c870 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2c880 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2c890 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2c8a0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2c8b0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2c8c0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2c8d0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2c8e0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2c8f0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2c900 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c910 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2c920 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2c930 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2c940 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2c950 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2c960 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2c970 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2c980 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2c990 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c9a0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2c9b0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2c9c0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2c9d0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2c9e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2c9f0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2ca00 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2ca10 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2ca20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2ca30 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2ca40 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2ca50 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2ca60 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2ca70 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2ca80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2ca90 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2caa0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2cab0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2cac0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2cad0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2cae0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2caf0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2cb00 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2cb10 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2cb20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2cb30 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2cb40 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2cb50 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2cb60 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2cb70 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2cb80 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2cb90 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2cba0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2cbb0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2cbc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cbd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2cbe0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2cbf0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2cc00 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2cc10 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2cc20 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2cc30 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2cc40 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2cc50 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2cc60 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2cc70 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2cc80 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2cc90 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2cca0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2ccb0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2ccc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2ccd0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2cce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ccf0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2cd00 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2cd10 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2cd20 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2cd30 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2cd40 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2cd50 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2cd60 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2cd70 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2cd80 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2cd90 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2cda0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2cdb0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2cdc0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2cdd0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2cde0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
2cdf0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2ce00 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2ce10 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2ce20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2ce30 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2ce40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ce50 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2ce60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ce70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2ce80 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2ce90 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2cea0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2ceb0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2cec0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2ced0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cee0 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2cef0 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2cf00 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2cf10 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2cf20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2cf30 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2cf40 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2cf50 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2cf60 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2cf70 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2cf80 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2cf90 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2cfa0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2cfb0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2cfc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2cfd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cfe0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2cff0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2d000 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2d010 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d020 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2d030 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2d040 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2d050 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d060 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2d070 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2d080 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2d090 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2d0a0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2d0b0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2d0c0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2d0d0 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2d0e0 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2d0f0 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2d100 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2d110 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2d120 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2d130 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2d140 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2d150 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2d160 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2d170 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2d180 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
2d190 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2d1a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d1b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d1c0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2d1d0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2d1e0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2d1f0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2d200 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2d210 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2d220 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2d230 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2d240 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2d250 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2d260 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2d270 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2d280 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2d290 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2d2a0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2d2b0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2d2c0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2d2d0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2d2e0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2d2f0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2d300 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2d310 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2d320 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2d330 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2d340 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2d350 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2d360 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2d370 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2d380 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2d390 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2d3a0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d3b0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2d3c0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2d3d0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2d3e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2d3f0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2d400 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2d410 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2d420 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2d430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2d440 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2d450 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2d460 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2d470 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2d480 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2d490 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2d4a0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2d4b0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2d4c0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2d4d0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2d4e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2d4f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2d500 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2d510 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2d520 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2d530 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2d540 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2d550 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2d560 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2d570 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2d580 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2d590 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2d5a0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2d5b0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2d5c0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2d5d0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2d5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d5f0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2d600 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2d610 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2d620 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2d630 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2d640 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d650 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2d660 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2d670 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2d680 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2d690 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2d6a0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2d6b0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2d6c0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2d6d0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2d6e0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2d6f0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2d700 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2d710 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2d720 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2d730 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2d740 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2d750 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2d760 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2d770 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2d780 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2d790 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2d7a0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2d7b0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2d7c0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2d7d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2d7e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2d7f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2d800 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2d810 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2d820 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2d830 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d840 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2d850 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2d860 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2d870 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2d880 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d890 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2d8a0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2d8b0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2d8c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2d8d0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2d8e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d8f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2d900 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2d910 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2d920 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2d930 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2d940 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2d950 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2d960 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2d970 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2d980 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2d990 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d9a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2d9b0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2d9c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2d9d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2d9e0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2d9f0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2da00 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2da10 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2da20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2da30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2da40 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2da50 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2da60 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2da70 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2da80 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2da90 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2daa0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2dab0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2dac0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2dad0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2dae0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2daf0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2db00 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2db10 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2db20 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2db30 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2db40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2db50 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2db60 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2db70 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2db80 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2db90 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2dba0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2dbb0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2dbc0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2dbd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2dbe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2dbf0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2dc00 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2dc10 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2dc20 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2dc30 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2dc40 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2dc50 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2dc60 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2dc70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2dc80 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2dc90 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2dca0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2dcb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2dcc0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2dcd0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2dce0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2dcf0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2dd00 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2dd10 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2dd20 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2dd30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2dd40 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2dd50 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2dd60 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2dd70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2dd80 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2dd90 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2dda0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2ddb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ddc0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2ddd0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2dde0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2ddf0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2de00 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2de10 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2de20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2de30 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2de40 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2de50 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2de60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2de70 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2de80 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2de90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2dea0 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2deb0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2dec0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ded0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2dee0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2def0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2df00 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2df10 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2df20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2df30 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2df40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2df50 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2df60 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2df70 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2df80 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2df90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2dfa0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2dfb0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2dfc0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2dfd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2dfe0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2dff0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2e000 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2e010 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2e020 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e030 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2e040 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e050 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2e060 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e070 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2e080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e090 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2e0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2e0b0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2e0c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e0d0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2e0e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e0f0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2e100 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2e110 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2e120 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2e130 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2e140 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2e150 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2e160 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2e170 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2e180 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2e190 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2e1a0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2e1b0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2e1c0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2e1d0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2e1e0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2e1f0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2e200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e210 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2e220 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e230 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2e240 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2e250 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2e260 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2e270 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2e280 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2e290 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2e2a0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2e2b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e2c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2e2d0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2e2e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e2f0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2e300 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2e310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e320 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2e330 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e340 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2e350 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2e360 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2e370 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2e380 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2e390 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2e3a0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2e3b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e3c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2e3d0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2e3e0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2e3f0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2e400 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2e410 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2e420 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2e430 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2e440 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2e450 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2e460 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e470 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2e480 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2e490 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e4a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2e4b0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2e4c0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2e4d0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2e4e0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2e4f0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2e500 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2e510 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2e520 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2e530 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2e540 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2e550 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2e560 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2e570 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2e580 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2e590 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2e5a0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2e5b0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2e5c0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2e5d0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2e5e0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2e5f0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2e600 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2e610 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2e620 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2e630 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2e640 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2e650 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2e660 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2e670 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2e680 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2e690 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2e6a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2e6b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e6c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2e6d0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2e6e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e6f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2e700 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2e710 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2e720 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2e730 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2e740 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2e750 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2e760 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2e770 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2e780 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2e790 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2e7a0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2e7b0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2e7c0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2e7d0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2e7e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2e7f0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2e800 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2e810 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2e820 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2e830 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2e840 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2e850 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2e860 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2e870 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2e880 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2e890 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2e8a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
2e8b0 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
2e8c0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2e8d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2e8e0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2e8f0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2e900 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2e910 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2e920 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2e930 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2e940 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2e950 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2e960 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2e970 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2e980 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2e990 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2e9a0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2e9b0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2e9c0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2e9d0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2e9e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2e9f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
2ea00 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
2ea10 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
2ea20 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
2ea30 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2ea40 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2ea50 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2ea60 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2ea70 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2ea80 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2ea90 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2eaa0 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2eab0 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2eac0 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2ead0 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2eae0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2eaf0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2eb00 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2eb10 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2eb20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2eb30 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2eb40 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2eb50 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2eb60 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2eb70 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2eb80 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2eb90 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2eba0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2ebb0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2ebc0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2ebd0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2ebe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ebf0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2ec00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ec10 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2ec20 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2ec30 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2ec40 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2ec50 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2ec60 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2ec70 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2ec80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2ec90 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2eca0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2ecb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2ecc0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2ecd0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2ece0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2ecf0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2ed00 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2ed10 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2ed20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2ed30 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2ed40 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2ed50 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2ed60 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2ed70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ed80 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2ed90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2eda0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2edb0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2edc0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2edd0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2ede0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2edf0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2ee00 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2ee10 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2ee20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2ee30 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2ee40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2ee50 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2ee60 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2ee70 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2ee80 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2ee90 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2eea0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
2eeb0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
2eec0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
2eed0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
2eee0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
2eef0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
2ef00 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
2ef10 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
2ef20 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2ef30 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
2ef40 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
2ef50 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
2ef60 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2ef70 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2ef80 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2ef90 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2efa0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2efb0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2efc0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2efd0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2efe0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2eff0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2f000 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2f010 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2f020 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2f030 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2f040 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2f050 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2f060 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2f070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2f080 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2f090 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2f0a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2f0b0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2f0c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2f0d0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2f0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f0f0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2f100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f110 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2f120 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2f130 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2f140 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f150 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2f160 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2f170 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2f180 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2f190 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2f1a0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2f1b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f1c0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2f1d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2f1e0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2f1f0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2f200 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2f210 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2f220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f230 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2f240 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f250 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2f260 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2f270 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2f280 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2f290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f2a0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2f2b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2f2c0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2f2d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f2e0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2f2f0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2f300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f310 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2f320 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2f330 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f340 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
2f350 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
2f360 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
2f370 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2f380 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
2f390 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
2f3a0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
2f3b0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2f3c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2f3d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2f3e0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
2f3f0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
2f400 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2f410 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2f420 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2f430 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2f440 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2f450 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2f460 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
2f470 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2f480 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2f490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f4a0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2f4b0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2f4c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2f4d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2f4e0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2f4f0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2f500 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2f510 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2f520 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2f530 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2f540 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2f550 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2f560 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2f570 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2f580 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2f590 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2f5a0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2f5b0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2f5c0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2f5d0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2f5e0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2f5f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f610 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f620 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2f630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f640 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2f650 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2f660 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2f670 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2f680 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f690 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2f6a0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2f6b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f6c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2f6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2f6e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f6f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2f700 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2f710 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2f720 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f730 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
2f740 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2f750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f770 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2f780 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f790 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2f7a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f7b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2f7c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2f7d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f7e0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2f7f0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2f800 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2f810 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f820 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2f830 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2f840 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2f850 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2f860 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2f870 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2f880 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2f890 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2f8a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f8b0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2f8c0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2f8d0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2f8e0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2f8f0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2f900 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2f910 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2f920 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2f930 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2f940 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2f950 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2f960 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2f970 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2f980 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2f990 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2f9a0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2f9b0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2f9c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2f9d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2f9e0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2f9f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2fa00 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2fa10 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2fa20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2fa30 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2fa40 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2fa50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2fa60 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2fa70 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2fa80 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2fa90 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2faa0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2fab0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2fac0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2fad0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2fae0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2faf0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2fb00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2fb10 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2fb20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2fb30 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2fb40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2fb50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2fb60 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2fb70 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2fb80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2fb90 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2fba0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fbb0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2fbc0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2fbd0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2fbe0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2fbf0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2fc00 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2fc10 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2fc20 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2fc30 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2fc40 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2fc50 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2fc60 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2fc70 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2fc80 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2fc90 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2fca0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2fcb0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2fcc0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2fcd0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2fce0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2fcf0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2fd00 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2fd10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fd20 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2fd30 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2fd40 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
2fd50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
2fd60 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2fd70 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
2fd80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fd90 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
2fda0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2fdb0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
2fdc0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
2fdd0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
2fde0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
2fdf0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
2fe00 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
2fe10 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
2fe20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2fe30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2fe40 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
2fe50 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
2fe60 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
2fe70 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
2fe80 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
2fe90 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
2fea0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2feb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
2fec0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2fed0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
2fee0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
2fef0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
2ff00 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
2ff10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2ff20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ff30 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2ff40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2ff50 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2ff60 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2ff70 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2ff80 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
2ff90 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2ffa0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
2ffb0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
2ffc0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
2ffd0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2ffe0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2fff0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30000 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30010 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30020 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
30030 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30040 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
30050 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
30060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
30070 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
30080 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
30090 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
300a0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
300b0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
300c0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
300d0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
300e0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
300f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
30100 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
30110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30120 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
30130 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
30140 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30160 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
30170 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
30180 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
30190 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
301a0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
301b0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
301c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
301d0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
301e0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
301f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
30200 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
30210 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
30220 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
30230 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
30240 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
30250 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
30260 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
30270 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
30280 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
30290 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
302a0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
302b0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
302c0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
302d0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
302e0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
302f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
30300 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
30310 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
30320 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
30330 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
30340 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
30350 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
30360 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
30370 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
30380 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
30390 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
303a0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
303b0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
303c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
303d0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
303e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
303f0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
30400 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
30410 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
30420 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
30430 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
30440 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
30450 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
30460 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
30470 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30480 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
30490 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
304a0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
304b0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
304c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
304d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
304e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
304f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30500 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
30510 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
30520 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
30530 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
30540 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
30550 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
30560 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
30570 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
30580 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
30590 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
305a0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
305b0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
305c0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
305d0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
305e0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
305f0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
30600 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
30610 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
30620 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
30630 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
30640 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
30650 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
30660 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
30670 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
30680 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
30690 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
306a0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
306b0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
306c0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
306d0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
306e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
306f0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
30700 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
30710 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
30720 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
30730 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
30740 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
30750 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
30760 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
30770 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
30780 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
30790 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
307a0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
307b0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
307c0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
307d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
307e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
307f0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
30800 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
30810 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
30820 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
30830 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
30840 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
30850 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
30860 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
30870 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
30880 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
30890 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
308a0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
308b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
308c0 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
308d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
308e0 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
308f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
30900 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
30910 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
30920 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
30930 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
30940 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
30950 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
30960 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
30970 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
30980 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
30990 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
309a0 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
309b0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
309c0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
309d0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
309e0 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
309f0 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
30a00 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
30a10 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
30a20 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
30a30 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
30a40 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
30a50 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
30a60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
30a70 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
30a80 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
30a90 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
30aa0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
30ab0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
30ac0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
30ad0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
30ae0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
30af0 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
30b00 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
30b10 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
30b20 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
30b30 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
30b40 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
30b50 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
30b60 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
30b70 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
30b80 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
30b90 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
30ba0 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
30bb0 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
30bc0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
30bd0 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
30be0 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
30bf0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
30c00 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
30c10 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
30c20 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
30c30 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
30c40 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
30c50 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
30c60 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
30c70 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
30c80 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
30c90 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
30ca0 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
30cb0 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
30cc0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
30cd0 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
30ce0 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
30cf0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
30d00 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
30d10 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
30d20 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
30d30 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
30d40 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
30d50 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
30d60 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
30d70 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
30d80 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
30d90 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
30da0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
30db0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
30dc0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
30dd0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
30de0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
30df0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
30e00 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
30e10 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
30e20 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
30e30 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
30e40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
30e50 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
30e60 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
30e70 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
30e80 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
30e90 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
30ea0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
30eb0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
30ec0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
30ed0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
30ee0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
30ef0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
30f00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
30f10 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
30f20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
30f30 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
30f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30f50 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
30f60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
30f70 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
30f80 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
30f90 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
30fa0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
30fb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
30fc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30fd0 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
30fe0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
30ff0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
31000 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31010 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
31020 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
31030 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
31040 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
31050 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
31060 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
31070 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
31080 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31090 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
310a0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
310b0 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
310c0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
310d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
310e0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
310f0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
31100 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31110 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
31120 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
31130 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
31140 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
31150 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
31160 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
31170 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31180 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
31190 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
311a0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
311b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
311c0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
311d0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
311e0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
311f0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
31200 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
31210 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
31220 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
31230 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
31240 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
31250 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
31260 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
31270 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
31280 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
31290 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
312a0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
312b0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
312c0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
312d0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
312e0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
312f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
31300 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
31310 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
31320 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
31330 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
31340 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
31350 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
31360 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
31370 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
31380 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
31390 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
313a0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
313b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
313c0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
313d0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
313e0 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
313f0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
31400 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
31410 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
31420 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
31430 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
31440 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
31450 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
31460 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
31470 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
31480 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
31490 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
314a0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
314b0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
314c0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
314d0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
314e0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
314f0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
31500 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
31510 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31520 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
31530 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31540 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
31550 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
31560 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
31570 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
31580 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
31590 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
315a0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
315b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
315c0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
315d0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
315e0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
315f0 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
31600 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
31610 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
31620 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
31630 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
31640 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
31650 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
31660 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
31670 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
31680 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
31690 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
316a0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
316b0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
316c0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
316d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
316e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
316f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
31700 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
31710 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
31720 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31730 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
31740 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
31750 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
31760 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
31770 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
31780 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
31790 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
317a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
317b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
317c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
317d0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
317e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
317f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31800 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
31810 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
31820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
31830 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31840 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
31850 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
31860 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
31870 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
31880 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
31890 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
318a0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
318b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
318c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
318d0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
318e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
318f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31900 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
31910 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
31920 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
31930 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
31940 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
31950 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
31960 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
31970 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
31980 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
31990 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
319a0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
319b0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
319c0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
319d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
319e0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
319f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
31a00 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
31a10 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
31a20 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
31a30 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
31a40 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
31a50 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
31a60 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
31a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31a80 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
31a90 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
31aa0 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
31ab0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
31ac0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
31ad0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31ae0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
31af0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
31b00 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
31b10 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
31b20 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
31b30 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
31b40 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
31b50 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
31b60 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
31b70 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
31b80 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
31b90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31ba0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
31bb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31bc0 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
31bd0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31be0 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
31bf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
31c00 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
31c10 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
31c20 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
31c30 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
31c40 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
31c50 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
31c60 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
31c70 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
31c80 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
31c90 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
31ca0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
31cb0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
31cc0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
31cd0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
31ce0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
31cf0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
31d00 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
31d10 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
31d20 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
31d30 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
31d40 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
31d50 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
31d60 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
31d70 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
31d80 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
31d90 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
31da0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
31db0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
31dc0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
31dd0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
31de0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31df0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
31e00 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31e10 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
31e20 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
31e30 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
31e40 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
31e50 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
31e60 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
31e70 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
31e80 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31e90 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
31ea0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
31eb0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
31ec0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
31ed0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
31ee0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
31ef0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31f00 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
31f10 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
31f20 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
31f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31f40 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
31f50 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
31f60 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
31f70 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
31f80 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
31f90 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
31fa0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
31fb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31fc0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
31fd0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
31fe0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
31ff0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
32000 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
32010 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
32020 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
32030 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
32040 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
32050 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
32060 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
32070 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
32080 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
32090 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
320a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
320b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
320c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
320d0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
320e0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
320f0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
32100 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
32110 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
32120 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
32130 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
32140 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
32150 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
32160 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32170 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32180 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
32190 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
321a0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
321b0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
321c0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
321d0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
321e0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
321f0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
32200 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
32210 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32220 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
32230 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
32240 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
32250 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32260 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
32270 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
32280 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32290 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
322a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
322b0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
322c0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
322d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
322e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
322f0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
32300 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32310 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
32320 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
32330 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
32340 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
32350 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
32360 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32370 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
32380 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
32390 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
323a0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
323b0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
323c0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
323d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
323e0 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
323f0 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
32400 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
32410 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
32420 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
32430 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
32440 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
32450 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
32460 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
32470 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
32480 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
32490 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
324a0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
324b0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
324c0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
324d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
324e0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
324f0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
32500 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
32510 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
32520 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
32530 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
32540 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
32550 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
32560 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
32570 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
32580 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
32590 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
325a0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
325b0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
325c0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
325d0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
325e0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
325f0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
32600 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
32610 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
32620 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
32630 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
32640 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
32650 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
32660 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
32670 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
32680 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
32690 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
326a0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
326b0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
326c0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
326d0 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
326e0 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
326f0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
32700 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
32710 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32720 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
32730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32740 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
32750 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
32760 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32770 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
32780 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
32790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
327a0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
327b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
327c0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
327d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
327e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
327f0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
32800 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
32810 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
32820 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32830 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
32840 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
32850 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
32860 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
32870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
32880 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
32890 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
328a0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
328b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
328c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
328d0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
328e0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
328f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
32900 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
32910 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
32920 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
32930 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
32940 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
32950 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
32960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
32970 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
32980 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
32990 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
329a0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
329b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
329c0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
329d0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
329e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
329f0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
32a00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
32a10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32a20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
32a30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32a40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
32a50 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
32a60 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
32a70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
32a80 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
32a90 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
32aa0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
32ab0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
32ac0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
32ad0 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
32ae0 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
32af0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
32b00 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
32b10 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
32b20 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
32b30 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
32b40 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
32b50 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
32b60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32b70 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
32b80 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
32b90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
32ba0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
32bb0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
32bc0 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
32bd0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
32be0 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
32bf0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32c00 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
32c10 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
32c20 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
32c30 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
32c40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32c50 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
32c60 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
32c70 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
32c80 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
32c90 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
32ca0 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
32cb0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
32cc0 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
32cd0 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
32ce0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
32cf0 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
32d00 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
32d10 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
32d20 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
32d30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
32d40 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
32d50 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
32d60 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
32d70 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
32d80 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
32d90 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
32da0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
32db0 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
32dc0 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
32dd0 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
32de0 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
32df0 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
32e00 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32e10 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
32e20 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
32e30 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
32e40 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
32e50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
32e60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32e70 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
32e80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
32e90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a  NULL pointer .**
32ea0 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c   when first call
32eb0 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  ed if N is less 
32ec0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
32ed0 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
32ee0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
32ef0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
32f00 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
32f10 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
32f20 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
32f30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32f40 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
32f50 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
32f60 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
32f70 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
32f80 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
32f90 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
32fa0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
32fb0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
32fc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32fd0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
32fe0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
32ff0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
33000 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
33010 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
33020 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57  allocation.)^  W
33030 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c  ithin the xFinal
33040 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73   callback, it is
33050 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65   customary to se
33060 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c  t.** N=0 in call
33070 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  s to sqlite3_agg
33080 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
33090 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a  ,N) so that no .
330a0 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d  ** pointless mem
330b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
330c0 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  occur..**.** ^SQ
330d0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
330e0 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
330f0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
33100 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
33110 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
33120 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
33130 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
33140 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
33150 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
33160 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
33170 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
33180 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
33190 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
331a0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
331b0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
331c0 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
331d0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
331e0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
331f0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
33200 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
33210 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
33220 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
33230 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
33240 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
33250 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
33260 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
33270 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
33280 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
33290 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
332a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
332b0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
332c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
332d0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
332e0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
332f0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
33300 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
33310 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
33320 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
33330 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
33340 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
33350 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
33360 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
33370 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33380 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
33390 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
333a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
333b0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
333c0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
333d0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
333e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
333f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33400 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
33410 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
33420 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
33430 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
33440 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33450 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
33460 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
33470 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
33480 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
33490 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
334a0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
334b0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
334c0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
334d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
334e0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
334f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
33500 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
33510 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
33520 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33530 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
33540 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
33550 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
33560 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33570 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
33580 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33590 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
335a0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
335b0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
335c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
335d0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
335e0 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
335f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
33600 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
33610 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
33620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
33630 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
33640 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  Data.**.** These
33650 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
33660 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
33670 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
33680 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
33690 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
336a0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
336b0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
336c0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
336d0 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
336e0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
336f0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
33700 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
33710 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
33720 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
33730 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
33740 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
33750 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
33760 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
33770 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
33780 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
33790 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
337a0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
337b0 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
337c0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
337d0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
337e0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
337f0 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
33800 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
33810 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
33820 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
33830 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
33840 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
33850 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
33860 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
33870 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
33880 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
33890 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
338a0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
338b0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
338c0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
338d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
338e0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
338f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33900 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
33910 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
33920 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
33930 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33940 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
33950 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
33960 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
33970 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
33980 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33990 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73  on. ^If there is
339a0 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20   no metadata.** 
339b0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
339c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  the function arg
339d0 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69  ument, this sqli
339e0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
339f0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
33a00 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
33a10 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
33a20 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
33a30 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69  xdata(C,N,P,X) i
33a40 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50  nterface saves P
33a50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72   as metadata for
33a60 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
33a70 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
33a80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33a90 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62   function.  ^Sub
33aa0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
33ab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
33ac0 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74  auxdata(C,N) ret
33ad0 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d  urn P from the m
33ae0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71  ost recent.** sq
33af0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33b00 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20  a(C,N,P,X) call 
33b10 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
33b20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f  is still valid o
33b30 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65  r.** NULL if the
33b40 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
33b50 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  en discarded..**
33b60 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c   ^After each cal
33b70 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
33b80 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
33b90 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74  ) where X is not
33ba0 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65   NULL,.** SQLite
33bb0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
33bc0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
33bd0 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61  tion X with para
33be0 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a  meter P exactly.
33bf0 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68  ** once, when th
33c00 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69  e metadata is di
33c10 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69  scarded..** SQLi
33c20 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69  te is free to di
33c30 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61  scard the metada
33c40 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20  ta at any time, 
33c50 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a  including: <ul>.
33c60 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65  ** <li> when the
33c70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
33c80 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
33c90 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a  r changes, or.**
33ca0 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69   <li> when [sqli
33cb0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
33cc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
33cd0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66  e()] is called f
33ce0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53  or the.**      S
33cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  QL statement, or
33d00 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71  .** <li> when sq
33d10 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33d20 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  a() is invoked a
33d30 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65  gain on the same
33d40 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a   parameter, or.*
33d50 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68  * <li> during th
33d60 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74  e original sqlit
33d70 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33d80 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d   call when a mem
33d90 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c  ory .**      all
33da0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
33db0 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  curs. </ul>)^.**
33dc0 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73  .** Note the las
33dd0 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74  t bullet in part
33de0 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73  icular.  The des
33df0 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a  tructor X in .**
33e00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33e10 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69  data(C,N,P,X) mi
33e20 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d  ght be called im
33e30 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
33e40 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  e the.** sqlite3
33e50 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
33e60 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65  nterface even re
33e70 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71  turns.  Hence sq
33e80 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33e90 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  a().** should be
33ea0 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65   called near the
33eb0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63   end of the func
33ec0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
33ed0 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ion and the.** f
33ee0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
33ef0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  tation should no
33f00 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f  t make any use o
33f10 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c  f P after.** sql
33f20 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33f30 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  () has been call
33f40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
33f50 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
33f60 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
33f70 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
33f80 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e  calls for.** fun
33f90 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73  ction parameters
33fa0 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c   that are compil
33fb0 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73  e-time constants
33fc0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65  , including lite
33fd0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
33fe0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61  d [parameters] a
33ff0 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63  nd expressions c
34000 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65  omposed from the
34010 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54   same.)^.**.** T
34020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
34030 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
34040 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
34050 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
34060 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
34070 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
34080 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
34090 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
340a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
340b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
340c0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
340d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
340e0 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
340f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
34100 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
34110 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
34120 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
34130 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
34140 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
34150 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
34160 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
34170 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
34180 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
34190 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
341a0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
341b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
341c0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
341d0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
341e0 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
341f0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
34200 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
34210 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
34220 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
34230 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
34240 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
34250 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
34260 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
34270 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
34280 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
34290 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
342a0 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
342b0 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
342c0 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
342d0 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
342e0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
342f0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
34300 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
34310 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
34320 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
34330 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
34340 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
34350 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
34360 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79  compilers..*/.ty
34370 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
34380 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
34390 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
343a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
343b0 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
343c0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
343d0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
343e0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
343f0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
34400 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
34410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34420 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
34430 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
34440 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
34450 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
34460 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
34470 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
34480 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
34490 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
344a0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
344b0 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
344c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
344d0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
344e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
344f0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
34500 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
34510 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
34520 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
34530 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
34540 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
34550 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
34560 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
34570 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
34580 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
34590 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
345a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
345b0 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
345c0 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
345d0 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
345e0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
345f0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
34600 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34610 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
34620 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34630 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
34640 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
34650 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34660 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
34670 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
34680 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
34690 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
346a0 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
346b0 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
346c0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
346d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
346e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
346f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
34700 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
34710 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
34720 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
34730 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34740 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
34750 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
34760 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
34770 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
34780 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
34790 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
347a0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
347b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
347c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
347d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
347e0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
347f0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
34800 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34810 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
34820 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
34830 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
34840 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
34850 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
34860 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34870 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
34880 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34890 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
348a0 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
348b0 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
348c0 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
348d0 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
348e0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
348f0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
34900 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
34910 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
34920 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34930 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
34940 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
34950 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
34960 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
34970 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
34980 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
34990 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
349a0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
349b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
349c0 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
349d0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
349e0 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
349f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34a00 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
34a10 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
34a20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
34a30 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
34a40 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
34a50 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
34a60 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
34a70 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
34a80 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
34a90 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
34aa0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
34ab0 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
34ac0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34ad0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34ae0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
34af0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34b00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34b10 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
34b20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34b30 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
34b40 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
34b50 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
34b60 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
34b70 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
34b80 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
34b90 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
34ba0 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
34bb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34bc0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
34bd0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34be0 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
34bf0 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
34c00 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
34c10 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
34c20 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
34c30 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
34c40 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
34c50 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
34c60 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
34c70 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
34c80 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
34c90 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
34ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34cb0 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
34cc0 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
34cd0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
34ce0 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
34cf0 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
34d00 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
34d10 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
34d20 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
34d30 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
34d40 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
34d50 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
34d60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34d70 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
34d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34d90 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
34da0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
34db0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
34dc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34dd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
34de0 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
34df0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
34e00 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
34e10 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
34e20 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
34e30 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
34e40 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
34e50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34e60 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
34e70 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
34e80 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
34e90 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
34ea0 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
34eb0 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
34ec0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
34ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34ee0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
34ef0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
34f00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
34f10 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
34f20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34f30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
34f40 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
34f50 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
34f60 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
34f70 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
34f80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34f90 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
34fa0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
34fb0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
34fc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34fd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34fe0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
34ff0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
35000 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
35010 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
35020 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35030 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
35040 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
35050 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
35060 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
35070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35080 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35090 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
350a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
350b0 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
350c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
350d0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
350e0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
350f0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
35100 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
35110 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
35120 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
35130 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
35140 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35150 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
35160 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
35170 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
35180 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
35190 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
351a0 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
351b0 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
351c0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
351d0 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
351e0 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
351f0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
35200 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
35210 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
35220 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
35230 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
35240 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
35250 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
35260 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
35270 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35280 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35290 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
352a0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
352b0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
352c0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
352d0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
352e0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
352f0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
35300 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
35310 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
35320 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
35330 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
35340 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
35350 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
35360 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
35370 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
35380 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
35390 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
353a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
353b0 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
353c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
353d0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
353e0 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
353f0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
35400 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
35410 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
35420 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
35430 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
35440 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
35450 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
35460 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
35470 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
35480 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
35490 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
354a0 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
354b0 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
354c0 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
354d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
354e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
354f0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
35500 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
35510 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
35520 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
35530 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
35540 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
35550 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
35560 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
35570 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
35580 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
35590 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
355a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
355b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
355c0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
355d0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
355e0 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
355f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
35600 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
35610 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
35620 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
35630 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
35640 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
35650 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
35660 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
35670 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
35680 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
35690 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
356a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
356b0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
356c0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
356d0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
356e0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
356f0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
35700 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
35710 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
35720 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
35730 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
35740 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
35750 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
35760 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
35770 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
35780 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
35790 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
357a0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
357b0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
357c0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
357d0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
357e0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
357f0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
35800 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
35810 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35820 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
35830 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
35840 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
35850 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
35860 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
35870 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
35880 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
35890 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
358a0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
358b0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
358c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
358d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
358e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
358f0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
35900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35910 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35920 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
35930 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
35940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35950 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
35960 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
35970 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
35980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35990 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
359a0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
359b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
359c0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
359d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
359e0 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
359f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
35a00 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
35a10 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
35a20 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
35a30 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
35a40 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
35a50 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
35a60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
35a70 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
35a80 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
35a90 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
35aa0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35ab0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
35ac0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
35ad0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
35ae0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35af0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
35b00 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
35b10 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
35b20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35b30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
35b40 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
35b50 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
35b60 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
35b70 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
35b80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35b90 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
35ba0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
35bb0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
35bc0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
35bd0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
35be0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
35bf0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
35c00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35c10 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
35c20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35c30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35c40 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
35c50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
35c60 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
35c70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35c80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35c90 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
35ca0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
35cb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35cc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35cd0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35ce0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
35cf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35d00 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
35d10 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
35d20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35d30 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
35d40 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
35d50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35d60 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
35d70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
35d80 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
35d90 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
35da0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
35db0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
35dc0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
35dd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35de0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
35df0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35e00 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
35e10 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
35e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35e30 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
35e40 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
35e50 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
35e60 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
35e70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35e80 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
35e90 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
35ea0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
35eb0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
35ec0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35ed0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
35ee0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35ef0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
35f00 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
35f10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35f20 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
35f30 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35f40 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
35f50 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
35f60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35f70 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
35f80 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
35f90 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
35fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
35fb0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
35fc0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
35fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35fe0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
35ff0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
36000 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
36010 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
36020 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
36030 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
36040 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
36050 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36060 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
36070 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
36080 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36090 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
360a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
360b0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
360c0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
360d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
360e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
360f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36100 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
36110 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
36120 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
36130 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36140 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
36150 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
36160 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
36170 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
36180 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
36190 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
361a0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
361b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
361c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
361d0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
361e0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
361f0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
36200 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
36210 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
36220 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
36230 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
36240 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36250 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
36260 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
36270 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
36280 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
36290 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
362a0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
362b0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
362c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
362d0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
362e0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
362f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
36300 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
36310 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
36320 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
36330 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36340 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
36350 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
36360 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
36370 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
36380 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
36390 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
363a0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
363b0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
363c0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
363d0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
363e0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
363f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
36400 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
36410 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
36420 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
36430 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
36440 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
36450 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36460 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
36470 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
36480 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
36490 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
364a0 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
364b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
364c0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
364d0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
364e0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
364f0 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
36500 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
36510 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
36520 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
36530 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
36540 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
36550 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
36560 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
36570 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
36580 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
36590 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
365a0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
365b0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
365c0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
365d0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
365e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
365f0 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
36600 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36610 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
36620 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
36630 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
36640 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
36650 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
36660 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
36670 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
36680 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
36690 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
366a0 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
366b0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
366c0 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
366d0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
366e0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
366f0 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
36700 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
36710 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
36720 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
36730 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
36740 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
36750 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
36760 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
36770 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
36780 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
36790 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
367a0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
367b0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
367c0 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
367d0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
367e0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
367f0 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
36800 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
36810 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
36820 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
36830 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
36840 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
36850 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
36860 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
36870 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
36880 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
36890 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
368a0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
368b0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
368c0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
368d0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
368e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
368f0 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
36900 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
36910 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
36920 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
36930 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
36940 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
36950 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
36960 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
36970 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
36980 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
36990 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
369a0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
369b0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
369c0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
369d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
369e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
369f0 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
36a00 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
36a10 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
36a20 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36a30 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
36a40 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
36a50 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
36a60 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
36a70 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
36a80 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36a90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
36aa0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
36ab0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36ac0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
36ad0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
36ae0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
36af0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
36b00 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
36b10 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
36b20 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
36b30 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
36b40 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
36b50 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
36b60 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
36b70 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
36b80 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
36b90 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
36ba0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
36bb0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
36bc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
36bd0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
36be0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
36bf0 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
36c00 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
36c10 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
36c20 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
36c30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36c40 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
36c50 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
36c60 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
36c70 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
36c80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36c90 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
36ca0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
36cb0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
36cc0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
36cd0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
36ce0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
36cf0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
36d00 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
36d10 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
36d20 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
36d30 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
36d40 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
36d50 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
36d60 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
36d70 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
36d80 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
36d90 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
36da0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
36db0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
36dc0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
36dd0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
36de0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
36df0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
36e00 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36e10 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
36e20 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
36e30 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
36e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36e50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
36e60 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
36e70 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
36e80 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36e90 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
36ea0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
36eb0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
36ec0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
36ed0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
36ee0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36ef0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
36f00 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
36f10 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
36f20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
36f30 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
36f40 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
36f50 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
36f60 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
36f70 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
36f80 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
36f90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36fa0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
36fb0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
36fc0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
36fd0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
36fe0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
36ff0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
37000 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
37010 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
37020 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
37030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37040 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
37050 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
37060 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
37070 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
37080 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
37090 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
370a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
370b0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
370c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
370d0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
370e0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
370f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37100 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
37110 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
37120 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
37130 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
37140 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
37150 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
37160 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
37170 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
37180 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37190 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
371a0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
371b0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
371c0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
371d0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
371e0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
371f0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
37200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37210 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
37220 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
37230 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
37240 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
37250 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
37260 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
37270 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
37280 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
37290 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
372a0 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
372b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
372c0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
372d0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
372e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
372f0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
37300 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
37310 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
37320 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37330 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
37340 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37350 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
37360 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37370 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
37380 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
37390 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
373a0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
373b0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
373c0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
373d0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
373e0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
373f0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
37400 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
37410 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
37420 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
37430 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
37440 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
37450 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
37460 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
37470 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37480 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
37490 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
374a0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
374b0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
374c0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
374d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
374e0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
374f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37500 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
37510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
37520 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37530 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
37540 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37550 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
37560 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
37570 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
37580 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
37590 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
375a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
375b0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
375c0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
375d0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
375e0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
375f0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
37600 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
37610 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
37620 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
37630 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
37640 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
37650 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
37660 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
37670 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
37680 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
37690 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
376a0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
376b0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
376c0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
376d0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
376e0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
376f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37700 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
37710 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
37720 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37730 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
37740 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
37750 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
37760 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
37770 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
37780 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  _key_v2(.  sqlit
37790 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
377a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
377b0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
377c0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
377d0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
377e0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
377f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
37800 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
37810 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
37820 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
37830 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
37840 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
37850 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
37860 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
37870 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
37880 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
37890 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
378a0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
378b0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
378c0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
378d0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
378e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
378f0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
37900 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
37910 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
37920 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
37930 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
37940 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
37950 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37970 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
37980 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
37990 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
379a0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
379b0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
379c0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
379d0 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71  3_rekey_v2(.  sq
379e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
379f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
37a00 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
37a10 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
37a20 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
37a30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61             /* Na
37a40 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
37a50 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  se */.  const vo
37a60 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
37a70 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
37a80 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
37a90 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
37aa0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
37ab0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
37ac0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
37ad0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
37ae0 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
37af0 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
37b00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
37b10 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
37b20 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
37b30 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
37b40 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
37b50 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
37b60 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
37b70 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
37b80 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
37b90 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
37ba0 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
37bb0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
37bc0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
37bd0 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
37be0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
37bf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
37c00 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
37c10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
37c20 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
37c30 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
37c40 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
37c50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37c60 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
37c70 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
37c80 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
37c90 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
37ca0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
37cb0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
37cc0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
37cd0 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
37ce0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
37cf0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
37d00 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
37d10 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
37d20 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
37d30 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
37d40 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
37d50 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
37d60 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
37d70 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
37d80 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
37d90 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
37da0 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
37db0 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
37dc0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
37dd0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
37de0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
37df0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
37e00 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
37e10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
37e20 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
37e30 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
37e40 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
37e50 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
37e60 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
37e70 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
37e80 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
37e90 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
37ea0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
37eb0 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
37ec0 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
37ed0 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
37ee0 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
37ef0 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
37f00 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
37f10 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
37f20 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
37f30 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
37f40 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
37f50 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20  agraphs..*/.int 
37f60 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
37f70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37f80 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
37f90 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
37fa0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
37fb0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
37fc0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
37fd0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
37fe0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
37ff0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
38000 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
38010 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
38020 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
38030 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
38040 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
38050 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
38060 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
38070 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
38080 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
38090 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
380a0 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
380b0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
380c0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
380d0 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
380e0 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
380f0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
38100 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
38110 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
38120 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
38130 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
38140 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
38150 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
38160 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
38170 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
38180 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
38190 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
381a0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
381b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
381c0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
381d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
381e0 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
381f0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
38200 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
38210 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
38220 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
38230 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
38240 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
38250 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
38260 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
38270 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
38280 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
38290 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
382a0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
382b0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
382c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
382d0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
382e0 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
382f0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
38300 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
38310 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
38320 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
38330 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38340 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
38350 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
38360 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
38370 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
38380 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
38390 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
383a0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
383b0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
383c0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
383d0 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
383e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
383f0 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
38400 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
38410 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
38420 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
38430 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
38440 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
38450 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
38460 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
38470 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
38480 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
38490 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
384a0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
384b0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
384c0 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
384d0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
384e0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
384f0 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
38500 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
38510 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
38520 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
38530 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
38540 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
38550 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
38560 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
38570 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
38580 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  n] or [sqlite3_o
38590 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77  pen_v2].  Otherw
385a0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
385b0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
385c0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
385d0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
385e0 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65   may fail.  Here
385f0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c   is an.** exampl
38600 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74  e of how to do t
38610 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69  his using C++ wi
38620 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52  th the Windows R
38630 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62  untime:.**.** <b
38640 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
38650 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68  ** LPCWSTR zPath
38660 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72   = Windows::Stor
38670 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e  age::Application
38680 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a  Data::Current->.
38690 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65  ** &nbsp;     Te
386a0 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50  mporaryFolder->P
386b0 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20  ath->Data();.** 
386c0 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39  char zPathBuf&#9
386d0 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23  1;MAX_PATH + 1&#
386e0 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a  93;;.** memset(z
386f0 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65  PathBuf, 0, size
38700 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a  of(zPathBuf));.*
38710 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74  * WideCharToMult
38720 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30  iByte(CP_UTF8, 0
38730 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61  , zPath, -1, zPa
38740 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50  thBuf, sizeof(zP
38750 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73  athBuf),.** &nbs
38760 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c  p;     NULL, NUL
38770 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  L);.** sqlite3_t
38780 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20  emp_directory = 
38790 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
387a0 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b  "%s", zPathBuf);
387b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
387c0 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54  kquote>.*/.SQLIT
387d0 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
387e0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
387f0 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
38800 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
38810 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
38820 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  ng Database File
38830 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66