/ Hex Artifact Content
Login

Artifact 11f33a3e968a9637d6fa4ae879b83edd171ac88f:


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 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5b90: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5ba0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5bb0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5bc0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5bd0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5be0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5bf0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5c00: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5c10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5c20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5c30: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5c40: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5c50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5c60: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5c70: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c90: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5ca0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5cb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ce0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5d00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5d40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5d50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5d90: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5da0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5dc0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5dd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5de0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5e10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5e20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5e50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5e60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5e70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5ea0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5eb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ec0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ee0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5ef0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5f00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5f30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5f40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5f70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5f80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5fb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5fc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5ff0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
6000: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6020: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
6030: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6070: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60a0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
60b0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
60c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
60d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
60e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60f0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
6100: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
6110: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6120: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6140: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6150: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6160: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6170: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6190: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
61a0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
61b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
61c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61e0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
61f0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
6200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6210: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6230: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
6240: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6250: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6260: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6270: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6280: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6290: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
62a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
62b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
62c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
62d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
62e0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
62f0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
6300: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
6310: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
6320: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
6330: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
6340: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6350: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6360: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6370: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6390: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
63a0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
63b0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
63c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
63d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
63e0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
63f0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6400: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6410: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6420: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6430: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6440: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6450: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6460: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6470: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6490: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
64a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
64b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
64c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
64d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
64e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
64f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6500: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6510: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6520: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6530: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6540: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6550: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6560: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6570: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6580: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6590: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
65a0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
65b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
65c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
65d0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
65e0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
65f0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6600: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6610: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6620: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6630: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6640: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6650: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6660: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6670: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6680: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6690: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
66a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
66b0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
66c0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
66d0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
66e0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
66f0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6700: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
6710: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
6720: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
6730: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
6740: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6750: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
6760: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
6770: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
6780: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
6790: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
67a0: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
67b0: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
67c0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
67d0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
67e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
67f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6800: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6820: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6830: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6840: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6860: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6870: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
6880: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6890: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
68a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68b0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
68c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68e0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
68f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6900: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6910: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6930: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6940: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6950: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
6960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6970: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
6980: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69a0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
69b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69c0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
69d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
69e0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
69f0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a10: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6a30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a40: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a50: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6a60: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6a80: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6a90: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ab0: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ad0: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
6ae0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6af0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6b00: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6b10: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6b20: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6b30: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6b40: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6b50: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6b60: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6b70: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6b80: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6b90: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6ba0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6bb0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6bc0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6bd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6be0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c00: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c20: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6c30: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6c40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6c50: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6c60: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6c70: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6c80: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6c90: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6ca0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6cb0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6cc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6cd0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6ce0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6cf0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6d00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d10: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6d20: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6d30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6d40: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6d50: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6d60: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6d70: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6d80: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6d90: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6da0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6db0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6dc0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6dd0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6de0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6df0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e00: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6e10: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6e20: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6e30: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6e40: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6e50: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e60: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6e70: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6e80: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6e90: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6ea0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6eb0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6ec0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6ed0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6ee0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6ef0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6f00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f10: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6f20: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f30: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6f40: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
6f50: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
6f60: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6f70: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6f80: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6f90: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6fa0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6fb0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6fc0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6fd0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6fe0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6ff0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7000: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7010: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7020: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7030: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7040: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7050: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7060: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7070: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7080: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7090: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
70a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
70b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
70c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
70d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
70e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
70f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7100: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7110: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7120: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7130: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7140: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7150: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7160: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7180: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7190: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
71a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
71b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
71c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
71d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
71e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
71f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7200: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7210: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7220: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7240: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7250: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7260: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7270: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7280: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7290: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
72a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
72b0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
72c0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
72d0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
72e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
72f0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7300: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7310: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7340: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7350: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7360: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7370: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7380: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7390: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
73a0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
73b0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
73c0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
73d0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
73e0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
73f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7400: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7410: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7420: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7430: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7440: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7450: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7460: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7470: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7480: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7490: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
74a0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
74b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
74c0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
74d0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
74e0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
74f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7500: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7510: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7520: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7530: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7540: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7550: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7560: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7570: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7580: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7590: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
75a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
75b0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
75c0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
75d0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
75e0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
75f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7600: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7610: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7620: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7640: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7650: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7660: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7670: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7680: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7690: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
76a0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
76b0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
76c0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
76d0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
76e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
76f0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7700: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7710: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7720: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7730: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7740: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7750: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7760: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7770: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7780: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7790: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
77a0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
77b0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
77c0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
77d0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
77e0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
77f0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7800: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7810: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7820: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7830: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7840: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7850: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7860: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7870: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7880: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7890: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
78a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
78b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
78c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
78d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
78e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7900: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
7910: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7920: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
7930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7940: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7950: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7960: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7970: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7980: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7990: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
79a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
79b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
79c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
79d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
79e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
79f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7a00: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7a10: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7a20: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7a30: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7a40: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7a50: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7a60: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7a70: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7a80: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7a90: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7aa0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7ab0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7ac0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7ad0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7ae0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7af0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7b20: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7b30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7b40: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7b50: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7b60: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7b70: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7b80: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7b90: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7ba0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7bb0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7bc0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7bd0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7be0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7bf0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7c00: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7c10: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7c20: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7c30: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7c40: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7c50: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7c60: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7c70: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7c80: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7c90: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7ca0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7cb0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7cc0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7cd0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7ce0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7cf0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7d00: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7d10: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7d20: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7d30: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7d40: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7d50: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7d60: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
7d70: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
7d80: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
7d90: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
7da0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
7db0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
7dc0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
7dd0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7de0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
7df0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
7e00: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
7e10: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
7e20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7e30: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
7e40: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
7e50: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
7e60: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
7e70: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
7e80: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
7e90: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
7ea0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
7eb0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
7ec0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
7ed0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
7ee0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
7ef0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
7f00: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
7f10: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
7f20: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
7f30: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
7f40: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
7f50: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
7f60: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7f70: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
7f80: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
7f90: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
7fa0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
7fb0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
7fc0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
7fd0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7fe0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ff0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8000: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8010: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8020: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8030: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8040: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8050: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8060: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8070: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8080: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8090: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
80a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
80b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
80c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
80e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8110: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8120: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8130: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
8140: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8170: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8180: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8190: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
81a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
81b0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
81c0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
81d0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
81e0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
81f0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8200: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8210: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8220: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8230: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8240: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8250: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8260: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8270: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8280: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8290: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
82a0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
82b0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
82c0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
82d0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
82e0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
82f0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8300: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8310: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8320: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8330: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8340: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8350: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8360: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8370: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8380: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
8390: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
83a0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
83b0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
83c0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
83d0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
83e0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
83f0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8400: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8410: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8420: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8430: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8440: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8450: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8460: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
8470: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
8480: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
8490: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
84a0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
84b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
84c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
84d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
84e0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
84f0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8500: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8510: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8520: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8530: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8540: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8550: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8560: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8580: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8590: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
85a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
85b0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
85c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
85d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
85e0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
85f0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8600: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8610: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8620: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8630: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8640: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8650: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8660: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8670: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8680: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8690: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
86a0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
86b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
86c0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
86d0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86f0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8700: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8710: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8720: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8730: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8740: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8750: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8760: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8770: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8780: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8790: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
87a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
87b0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
87c0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
87d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
87e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
87f0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
8800: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
8810: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
8820: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
8830: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8840: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
8860: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
8870: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8880: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8890: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
88a0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
88b0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
88c0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
88d0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
88e0: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
88f0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8900: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8910: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
8920: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
8930: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8940: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
8950: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
8960: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
8970: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8980: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
8990: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
89a0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
89b0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
89c0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
89d0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
89e0: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
89f0: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
8a00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8a10: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8a20: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8a30: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8a40: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8a50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8a60: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8a70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8a80: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8a90: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
8aa0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8ab0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8ac0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8ad0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8ae0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8af0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b00: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8b10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8b20: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8b30: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8b40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8b60: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8b70: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8b90: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8ba0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8bb0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8bc0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8bd0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8be0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8bf0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8c00: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8c10: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8c20: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8c30: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8c40: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8c50: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8c60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8c70: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8c80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8c90: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ca0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8cb0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8cc0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8cd0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8ce0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8cf0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8d00: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8d10: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8d20: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8d30: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8d40: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8d50: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8d60: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8d70: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8d80: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8d90: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8da0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8db0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8dc0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8dd0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8de0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8df0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8e00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8e10: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8e20: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8e30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8e40: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8e50: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8e60: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8e70: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8e80: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8e90: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8ea0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8eb0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8ec0: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8ed0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8ee0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8ef0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8f00: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8f10: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8f20: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8f30: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8f40: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8f50: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8f60: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
8f70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
8f80: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
8f90: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
8fa0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
8fb0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8fc0: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8fd0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8fe0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8ff0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9000: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9010: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9020: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9040: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9050: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9060: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9070: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9080: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9090: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
90a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
90b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
90c0: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
90d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
90e0: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
90f0: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
9100: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
9110: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9120: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9130: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9140: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9150: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9160: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9170: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9180: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9190: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
91a0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
91b0: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
91c0: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
91d0: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
91e0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
91f0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9200: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9210: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9220: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9230: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9240: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9250: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9260: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9270: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9280: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9290: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
92a0: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
92b0: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
92c0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
92d0: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
92e0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
92f0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9300: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9310: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9320: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9330: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9340: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9350: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9360: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9370: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9380: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9390: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
93a0: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
93b0: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
93c0: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
93d0: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
93e0: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
93f0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9400: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9410: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9420: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9430: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9440: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9450: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9460: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9470: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9480: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9490: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
94a0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
94b0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
94c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
94d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
94e0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
94f0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9500: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9510: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9520: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9530: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9540: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9550: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9560: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9570: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9580: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9590: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
95a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
95b0: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
95c0: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
95d0: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
95e0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
95f0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9600: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9610: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9620: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9630: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9640: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9650: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9660: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9670: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9680: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9690: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
96a0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
96b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
96c0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
96d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
96e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96f0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9700: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9710: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9720: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9730: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9740: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9750: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9760: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9770: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9780: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9790: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
97a0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
97b0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
97c0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
97d0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
97e0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
97f0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9800: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9810: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9820: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9830: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9840: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9850: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9860: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9870: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9880: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9890: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
98a0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
98b0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
98c0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
98d0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
98e0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
98f0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9900: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9910: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9920: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9930: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9940: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9950: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9960: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9970: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9980: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9990: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
99a0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
99b0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
99c0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
99d0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
99e0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
99f0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9a00: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9a10: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9a20: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9a30: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9a40: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9a50: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9a60: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9a70: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9a80: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9a90: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9aa0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9ab0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9ac0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9ad0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9ae0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9af0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9b20: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9b30: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9b40: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9b50: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9b60: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9b70: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9b80: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9b90: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9ba0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
9bb0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
9bc0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9bd0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9be0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9bf0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9c00: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9c10: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9c20: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9c30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9c40: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9c50: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9c60: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9c70: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9c80: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9c90: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9ca0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
9cb0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
9cc0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9cd0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9ce0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9cf0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9d00: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9d10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9d20: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9d30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9d40: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9d50: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d60: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
9d70: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
9d80: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
9d90: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
9da0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9db0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
9dc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9dd0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9de0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9df0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9e00: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9e10: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9e20: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9e30: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9e40: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9e50: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9e60: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9e70: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9e80: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9e90: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9ea0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
9eb0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
9ec0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9ed0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9ee0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9ef0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9f00: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9f10: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9f20: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9f30: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9f40: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9f50: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9f60: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9f70: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9f80: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9f90: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9fa0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9fb0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9fc0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9fd0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9fe0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9ff0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a000: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a010: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a020: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a030: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a040: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a050: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a060: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a070: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a080: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a090: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a0a0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a0b0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a0c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a0d0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a0e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a0f0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a100: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a110: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a120: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a130: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a140: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a150: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a160: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a170: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a180: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a190: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a1a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a1b0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a1c0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a1d0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a1e0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a1f0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a200: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a210: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a220: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a230: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a240: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a250: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a260: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a270: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a280: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a290: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a2a0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a2b0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a2c0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a2d0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a2e0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a2f0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a300: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a310: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a320: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a330: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a340: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a350: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a360: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a370: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a380: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a390: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a3a0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a3b0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a3c0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a3d0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a3e0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a3f0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a400: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a410: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a420: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a430: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a440: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a450: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a460: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a470: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a480: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a490: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a4a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a4b0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a4c0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a4d0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a4e0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a4f0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a500: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a510: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a520: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a530: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a540: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a550: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a560: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a570: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a580: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a590: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a5a0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a5b0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a5c0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a5d0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a5e0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a5f0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a600: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a610: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a620: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a630: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a640: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a650: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a660: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a670: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a680: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a690: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a6a0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a6b0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a6c0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a6d0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a6e0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a6f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a700: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a710: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a720: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a730: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a740: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a750: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a760: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a770: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a780: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a790: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a7a0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a7b0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a7c0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a7d0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a7e0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a7f0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a800: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a810: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a820: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a830: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a840: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a850: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a860: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a870: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a880: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a890: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a8a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a8b0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a8c0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a8d0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a8e0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a8f0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a900: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a910: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a920: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a930: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a940: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a950: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a960: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a970: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a980: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a990: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a9a0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a9b0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a9c0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a9d0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a9e0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a9f0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
aa00: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
aa10: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
aa20: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
aa30: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
aa40: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
aa50: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
aa60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa80: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
aa90: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
aaa0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
aab0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
aac0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
aad0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
aae0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
aaf0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
ab10: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
ab20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab30: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
ab40: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
ab50: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
ab60: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
ab70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
ab80: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
ab90: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
aba0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
abb0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
abc0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
abd0: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
abe0: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
abf0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
ac00: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
ac10: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
ac20: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
ac30: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
ac40: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
ac50: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
ac60: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
ac70: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
ac80: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
ac90: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
aca0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
acb0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
acc0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
acd0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
ace0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
acf0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
ad00: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
ad10: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
ad20: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
ad30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
ad40: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
ad50: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
ad60: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
ad70: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
ad80: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
ad90: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
ada0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
adb0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
adc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
add0: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
ade0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
adf0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
ae00: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
ae10: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
ae20: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
ae30: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
ae40: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
ae50: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
ae60: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
ae70: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
ae80: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
ae90: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aea0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
aeb0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
aec0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aed0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aee0: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aef0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
af00: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
af10: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
af20: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
af30: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
af40: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
af50: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
af60: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
af70: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
af80: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
af90: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
afa0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
afb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
afc0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
afe0: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
aff0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b000: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b010: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b020: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b030: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b040: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b050: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b060: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b070: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b080: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b090: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b0a0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b0b0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b0c0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b0d0: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b0e0: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b0f0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b100: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b110: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b120: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b130: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b140: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b150: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b160: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b170: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b180: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b190: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b1a0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b1b0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b1c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b1d0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b1e0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b1f0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b200: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b210: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b220: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b230: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b240: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b250: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b260: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b270: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b280: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b290: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b2a0: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b2b0: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b2c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b2d0: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b2e0: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b2f0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b300: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b310: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b320: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b330: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b340: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
b350: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
b360: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
b370: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
b380: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
b390: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
b3a0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
b3b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
b3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b3d0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
b3e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b3f0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
b400: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
b410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
b420: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
b430: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
b440: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
b450: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
b460: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
b470: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
b480: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
b490: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
b4a0: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
b4b0: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
b4c0: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
b4d0: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
b4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
b4f0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
b500: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b510: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b520: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
b530: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
b540: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
b550: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
b560: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
b570: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
b580: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
b590: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
b5a0: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
b5b0: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
b5c0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
b5d0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
b5e0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
b5f0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
b600: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
b610: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
b620: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  ned..**.** </ul>
b630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b640: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
b650: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b660: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
b670: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
b680: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
b690: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b6a0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
b6b0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
b6c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
b6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b700: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
b710: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
b720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b730: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
b740: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
b750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b760: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
b770: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
b780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b790: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
b7a0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
b7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7c0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
b7d0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
b7e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b7f0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
b800: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
b810: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
b820: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
b830: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
b840: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
b850: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
b860: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
b870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
b880: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
b890: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b8b0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
b8c0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
b8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b8e0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
b8f0: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
b900: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b910: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
b920: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b940: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
b950: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
b960: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
b970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b980: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b990: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
b9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9c0: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
b9d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
b9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9f0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
ba00: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba20: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
ba30: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 0a 2f  NDLE       23../
ba40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ba50: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
ba60: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
ba70: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
ba80: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
ba90: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
baa0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
bab0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
bac0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
bad0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
bae0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
baf0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
bb00: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
bb10: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
bb20: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
bb30: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
bb40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
bb50: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
bb60: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
bb70: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
bb80: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
bb90: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
bba0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
bbb0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
bbc0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
bbd0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bbe0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
bbf0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
bc00: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bc10: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
bc20: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
bc30: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
bc40: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
bc50: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
bc60: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
bc70: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
bc80: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
bc90: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
bca0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
bcb0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
bcc0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
bcd0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
bce0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
bcf0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
bd00: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
bd10: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
bd20: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
bd30: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
bd40: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
bd50: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
bd60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
bd70: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
bd80: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
bd90: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
bda0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
bdb0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
bdc0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
bdd0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
bde0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
bdf0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
be00: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
be10: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
be20: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
be30: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
be40: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
be50: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
be60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
be70: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
be80: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
be90: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
bea0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
beb0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
bec0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
bed0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
bee0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
bef0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
bf00: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
bf10: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
bf20: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
bf30: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
bf40: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
bf50: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
bf60: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
bf70: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
bf80: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
bf90: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
bfa0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
bfb0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
bfc0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
bfd0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
bfe0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
bff0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
c000: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
c010: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
c020: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
c030: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
c040: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c050: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
c060: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
c070: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
c080: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
c090: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
c0a0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
c0b0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
c0c0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
c0d0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
c0e0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
c0f0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
c100: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
c110: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
c120: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
c130: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
c140: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
c150: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
c160: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
c170: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
c180: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
c190: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
c1a0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
c1b0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
c1c0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
c1d0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
c1e0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
c1f0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
c200: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
c210: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
c220: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
c230: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
c240: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
c250: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c260: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
c270: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
c280: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
c290: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
c2a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
c2b0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
c2c0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
c2d0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
c2e0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
c2f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c300: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
c310: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
c320: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
c330: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
c340: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
c350: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
c360: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
c370: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
c380: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
c390: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
c3a0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
c3b0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
c3c0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
c3d0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
c3e0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
c3f0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
c400: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
c410: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
c420: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
c430: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
c440: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
c450: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
c460: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
c470: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
c480: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c490: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c4a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
c4b0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
c4c0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
c4d0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
c4e0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
c4f0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
c500: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
c510: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
c520: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
c530: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
c540: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
c550: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
c560: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c570: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
c580: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
c590: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
c5a0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
c5b0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
c5c0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
c5d0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
c5e0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
c5f0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
c600: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
c610: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
c620: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
c630: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
c640: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
c650: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
c660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c670: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
c680: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
c690: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
c6a0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
c6b0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
c6c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c6d0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
c6e0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
c6f0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
c700: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
c710: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
c720: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c730: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c740: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
c750: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
c760: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
c770: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
c780: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c790: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
c7a0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c7b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
c7c0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c7d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
c7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c7f0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
c800: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
c820: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
c830: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c840: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
c850: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c860: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
c870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c880: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
c890: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
c8a0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
c8b0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
c8c0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
c8d0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
c8e0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
c8f0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
c900: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
c910: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
c920: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
c930: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
c940: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
c950: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
c960: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
c970: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
c980: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
c990: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
c9a0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
c9b0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
c9c0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
c9d0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
c9e0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
c9f0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
ca00: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
ca10: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
ca20: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
ca30: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
ca40: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
ca50: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
ca60: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
ca70: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
ca80: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
ca90: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
caa0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
cab0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
cac0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
cad0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
cae0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
caf0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
cb00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
cb10: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cb20: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
cb30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
cb40: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
cb50: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
cb60: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cb70: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
cb80: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cb90: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
cba0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
cbb0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
cbc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
cbd0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
cbe0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
cbf0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
cc00: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
cc10: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
cc20: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
cc30: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
cc40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc50: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
cc60: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
cc70: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
cc80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
cc90: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
cca0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
ccb0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
ccc0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
ccd0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
cce0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
ccf0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
cd00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
cd10: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
cd20: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
cd30: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
cd40: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
cd50: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
cd60: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
cd70: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
cd80: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
cd90: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
cda0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
cdb0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
cdc0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
cdd0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
cde0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
cdf0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
ce00: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
ce10: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
ce20: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
ce30: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
ce40: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
ce50: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
ce60: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
ce70: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
ce80: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
ce90: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
cea0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
ceb0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
cec0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
ced0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
cee0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
cef0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
cf00: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
cf10: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
cf20: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
cf30: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
cf40: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
cf50: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
cf60: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
cf70: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
cf80: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
cf90: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
cfa0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
cfb0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
cfc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
cfd0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
cfe0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
cff0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
d000: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
d010: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
d020: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
d030: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
d040: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
d050: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
d060: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
d070: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
d080: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
d090: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d0a0: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
d0b0: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
d0c0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
d0d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d0e0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
d0f0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d100: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
d110: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
d120: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d130: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
d140: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d150: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
d160: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
d170: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
d180: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
d190: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
d1a0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
d1b0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
d1c0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
d1d0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
d1e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
d1f0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
d200: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d210: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
d220: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
d230: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
d240: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
d250: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d260: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
d270: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
d280: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
d290: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
d2a0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
d2b0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
d2c0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
d2d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
d2e0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
d2f0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
d300: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
d310: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
d320: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
d330: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
d340: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
d350: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
d360: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
d370: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d380: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
d390: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
d3a0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
d3b0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
d3c0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
d3d0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
d3e0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
d3f0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
d400: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d410: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
d420: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
d430: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
d440: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
d450: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
d460: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
d470: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
d480: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
d490: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
d4a0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
d4b0: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
d4c0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
d4d0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
d4e0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
d4f0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
d500: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
d510: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
d520: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
d530: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
d540: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
d550: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
d560: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
d570: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
d580: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
d590: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
d5a0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d5b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
d5c0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
d5d0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
d5e0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
d5f0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
d600: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
d610: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
d620: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
d630: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
d640: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
d650: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d660: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
d670: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
d680: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
d690: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
d6a0: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
d6b0: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
d6c0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
d6d0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
d6e0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
d6f0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
d700: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
d710: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
d720: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
d730: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
d740: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
d750: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
d760: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
d770: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
d780: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
d790: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
d7a0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
d7b0: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
d7c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
d7d0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
d7e0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
d7f0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
d800: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
d810: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
d820: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
d830: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
d840: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
d850: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
d860: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
d870: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
d880: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
d890: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
d8a0: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
d8b0: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
d8c0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
d8d0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
d8e0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
d8f0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
d900: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
d910: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
d920: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
d930: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
d940: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
d950: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
d960: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
d970: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
d980: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
d990: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
d9a0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d9b0: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
d9c0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
d9d0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
d9e0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
d9f0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
da00: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
da10: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
da20: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
da30: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
da40: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
da50: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
da60: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
da70: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
da80: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
da90: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
daa0: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
dab0: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
dac0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
dad0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
dae0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
daf0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
db00: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
db10: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
db20: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
db30: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
db40: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
db50: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
db60: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
db70: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
db80: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
db90: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
dba0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
dbb0: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
dbc0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
dbd0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dbe0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
dbf0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
dc00: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
dc10: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
dc20: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
dc30: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
dc40: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
dc50: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
dc60: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
dc70: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dc80: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
dc90: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
dca0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
dcb0: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
dcc0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
dcd0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dce0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dcf0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
dd00: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
dd10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dd20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dd30: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
dd40: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
dd50: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
dd60: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
dd70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dd80: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
dd90: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
dda0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
ddb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ddc0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
ddd0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
dde0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
ddf0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
de00: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
de10: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
de20: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
de30: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
de40: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
de50: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
de60: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
de70: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
de80: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
de90: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
dea0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
deb0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
dec0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
ded0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
dee0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
def0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
df00: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
df10: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
df20: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
df30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
df40: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
df50: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
df60: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
df70: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
df80: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
df90: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
dfa0: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
dfb0: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
dfc0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
dfd0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
dfe0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
dff0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
e000: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
e010: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e020: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e030: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e040: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
e050: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e060: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
e070: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
e080: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
e090: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
e0a0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
e0b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e0c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e0d0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e0e0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
e0f0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
e100: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
e110: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e120: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
e130: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
e140: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
e150: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e160: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e170: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e180: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e190: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
e1a0: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
e1b0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e1c0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
e1d0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
e1e0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
e1f0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
e200: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
e210: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
e220: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
e230: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
e240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e250: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e260: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
e270: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
e280: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
e290: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
e2a0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
e2b0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
e2c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
e2d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
e2e0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
e2f0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
e300: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
e310: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
e320: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
e330: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
e340: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
e350: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
e360: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
e370: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
e380: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
e390: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
e3a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e3b0: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
e3c0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e3d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
e3e0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
e3f0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
e400: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
e410: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
e420: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
e430: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
e440: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
e450: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
e460: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
e470: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e480: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
e490: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
e4a0: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
e4b0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e4c0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
e4d0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
e4e0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
e4f0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
e500: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
e510: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e520: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
e530: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e540: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e550: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
e560: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e570: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
e580: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
e590: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
e5a0: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
e5b0: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
e5c0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
e5d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
e5e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
e5f0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
e600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e610: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
e620: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
e630: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
e640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
e650: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e660: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
e670: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e680: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
e690: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
e6a0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e6b0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e6c0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
e6d0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
e6e0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
e6f0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
e700: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
e710: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
e720: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
e730: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
e740: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
e750: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
e760: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
e770: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
e780: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e790: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e7a0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e7b0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e7c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
e7d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e7e0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
e7f0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e800: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e810: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e820: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e830: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e840: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
e850: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
e860: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
e870: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
e880: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
e890: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
e8a0: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
e8b0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
e8c0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
e8d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e8e0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
e8f0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
e900: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
e910: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e920: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
e930: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
e940: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
e950: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
e960: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
e970: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
e980: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
e990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e9a0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
e9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e9c0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
e9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9e0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
e9f0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
ea00: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
ea10: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
ea20: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
ea30: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
ea40: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
ea50: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
ea60: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
ea70: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
ea80: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
ea90: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
eaa0: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
eab0: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
eac0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
ead0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
eae0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
eaf0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
eb00: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
eb10: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
eb20: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
eb30: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
eb40: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
eb50: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
eb60: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
eb70: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
eb80: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
eb90: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
eba0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
ebb0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
ebc0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
ebd0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
ebe0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
ebf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
ec00: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
ec10: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
ec20: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
ec30: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
ec40: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
ec50: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
ec60: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
ec70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
ec80: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
ec90: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
eca0: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
ecb0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
ecc0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
ecd0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
ece0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
ecf0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
ed00: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
ed10: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ed20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ed30: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
ed40: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
ed50: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
ed60: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
ed70: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ed80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ed90: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
eda0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
edb0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
edc0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
edd0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
ede0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
edf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee00: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
ee10: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
ee20: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
ee30: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
ee40: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
ee50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ee60: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
ee70: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ee80: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
ee90: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
eea0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
eeb0: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
eec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eed0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
eee0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
eef0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ef00: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
ef10: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
ef20: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
ef30: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
ef40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef50: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef60: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
ef70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ef80: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
ef90: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
efa0: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
efb0: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
efc0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
efd0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
efe0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
eff0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
f000: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
f010: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
f020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f030: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
f040: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
f050: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
f060: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
f070: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
f080: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
f090: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
f0a0: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
f0b0: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
f0c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0d0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
f0e0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f0f0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
f100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f110: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
f120: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f130: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
f140: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f150: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
f160: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
f170: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
f180: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
f190: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
f1a0: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
f1b0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
f1c0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
f1d0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
f1e0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
f1f0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
f200: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
f210: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
f220: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
f230: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
f240: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
f250: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f260: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f270: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
f280: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
f290: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
f2a0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
f2b0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
f2c0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
f2d0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
f2e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
f2f0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f300: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
f310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f320: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
f330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f340: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
f350: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
f360: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
f370: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
f380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f390: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
f3a0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
f3b0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
f3c0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
f3d0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
f3e0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
f3f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f400: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
f410: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
f420: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
f430: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f440: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
f450: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
f460: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f470: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
f480: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f490: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
f4a0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
f4b0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
f4c0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
f4d0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
f4e0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
f4f0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
f500: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
f510: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f520: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
f530: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
f540: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f550: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f560: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
f570: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
f580: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
f590: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
f5a0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
f5b0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
f5c0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
f5d0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
f5e0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f5f0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
f600: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
f610: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
f620: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
f630: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
f640: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
f650: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
f660: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
f670: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
f680: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f690: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f6a0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
f6b0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
f6c0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
f6d0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
f6e0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
f6f0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
f700: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
f710: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
f720: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
f730: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
f740: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
f750: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
f760: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
f770: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
f780: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
f790: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
f7a0: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
f7b0: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
f7c0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f7d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
f7e0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
f7f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f800: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
f810: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
f820: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f830: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
f840: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
f850: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f860: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
f870: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
f880: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
f890: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f8a0: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
f8b0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
f8c0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
f8d0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
f8e0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f8f0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
f900: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
f910: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
f920: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
f930: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
f940: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
f950: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
f960: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
f970: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
f980: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
f990: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
f9a0: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
f9b0: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
f9c0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
f9d0: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
f9e0: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
f9f0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
fa00: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
fa10: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
fa20: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
fa30: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
fa40: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
fa50: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
fa60: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
fa70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fa80: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fa90: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
faa0: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
fab0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fac0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
fad0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
fae0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
faf0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
fb00: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
fb10: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
fb20: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
fb30: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
fb40: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
fb50: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
fb60: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
fb70: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
fb80: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
fb90: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fba0: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
fbb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fbc0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
fbd0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
fbe0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fbf0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fc00: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fc10: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
fc20: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
fc30: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
fc40: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
fc50: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
fc60: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
fc70: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
fc80: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
fc90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
fca0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
fcb0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
fcc0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
fcd0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
fce0: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
fcf0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
fd00: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
fd10: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
fd20: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
fd30: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
fd40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
fd50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fd60: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
fd70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
fd80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
fd90: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
fda0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
fdb0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
fdc0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
fdd0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
fde0: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
fdf0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
fe00: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
fe10: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
fe20: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
fe30: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
fe40: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
fe50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
fe60: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
fe70: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
fe80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe90: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
fea0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
feb0: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
fec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fed0: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
fee0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
fef0: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
ff00: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
ff10: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
ff20: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
ff30: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
ff40: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
ff50: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
ff60: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ff70: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
ff80: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
ff90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
ffa0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
ffb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ffc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ffd0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ffe0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fff0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
10000 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
10010 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10020 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10030 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10040 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10050 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10060 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10080 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10090 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
100a0 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
100b0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
100c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
100d0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
100e0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
100f0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10100 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10110 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10120 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10130 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10140 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10150 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10170 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10190 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
101a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
101b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
101c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
101d0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
101e0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
101f0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10200 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10220 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10230 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10240 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10250 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10260 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10270 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10290 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
102a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
102b0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
102c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
102d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
102e0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
102f0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10300 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10310 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10320 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10330 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10340 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10350 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10360 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10370 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10380 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10390 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
103a0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
103b0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
103c0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
103d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
103e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
103f0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10400 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10410 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10420 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
10430 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
10440 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10450 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10460 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10470 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10480 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10490 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
104a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
104b0 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
104c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
104d0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
104e0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
104f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10500 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10510 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10520 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10530 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10540 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10550 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10570 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10580 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10590 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
105a0 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
105b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105c0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
105d0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
105e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
105f0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10600 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10610 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10620 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10630 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10640 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10660 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10670 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10680 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10690 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
106a0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
106b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
106c0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
106d0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
106e0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
106f0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10700 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10710 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10720 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10730 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10740 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
10750 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
10760 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10770 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10780 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10790 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
107a0 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
107b0 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
107c0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
107d0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
107e0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
107f0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10800 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10810 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
10820 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
10830 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
10840 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
10850 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
10860 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10870 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10880 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10890 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
108a0 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
108b0 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
108c0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
108d0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
108e0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
108f0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10900 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
10910 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
10920 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
10930 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
10940 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
10950 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
10960 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10970 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10980 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10990 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
109a0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
109b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
109c0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
109d0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
109e0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
109f0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10a00 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
10a10 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
10a20 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
10a30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10a40 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
10a50 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
10a60 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10a70 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10a80 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10a90 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10aa0 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10ab0 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10ac0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10ad0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10ae0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10af0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10b00 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10b10 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
10b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
10b30 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
10b40 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
10b50 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
10b60 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10b70 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10b80 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10b90 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10ba0 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10bb0 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10bc0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10bd0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10be0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10bf0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10c00 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
10c10 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
10c20 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
10c30 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
10c40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
10c50 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
10c60 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
10c70 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
10c80 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
10c90 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10ca0 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
10cb0 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
10cc0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
10cd0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
10ce0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10cf0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
10d00 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
10d10 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
10d20 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
10d30 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
10d40 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
10d50 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
10d60 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10d70 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
10d80 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
10d90 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10da0 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
10db0 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
10dc0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
10dd0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
10de0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
10df0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
10e00 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
10e10 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
10e20 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
10e30 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
10e40 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
10e50 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
10e60 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
10e70 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
10e80 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
10e90 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
10ea0 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
10eb0 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
10ec0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10ed0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
10ee0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
10ef0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
10f00 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
10f10 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
10f20 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
10f30 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
10f40 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
10f50 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10f60 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
10f70 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
10f80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
10f90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
10fa0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10fb0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
10fc0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
10fd0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
10fe0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
10ff0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11000 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
11010 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11030 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11040 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11050 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11060 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11070 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11080 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11090 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
110a0 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
110b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
110c0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
110d0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
110e0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
110f0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11100 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11110 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11120 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11130 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11140 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11150 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11160 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11170 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11180 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
111a0 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
111b0 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
111c0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
111d0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
111e0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
111f0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11200 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11210 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11220 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11230 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11240 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11250 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11260 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11270 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11280 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11290 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
112a0 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
112b0 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
112c0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
112d0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
112e0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
112f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11300 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11310 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11320 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11330 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11340 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11350 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11370 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11380 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11390 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
113a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
113b0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
113c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
113d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
113e0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
113f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11400 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11410 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11420 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11430 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11440 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11450 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11460 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11470 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11480 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11490 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
114a0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
114b0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
114c0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
114d0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
114e0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
114f0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11500 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11510 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11520 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11530 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11540 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11550 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11560 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11570 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11580 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11590 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
115a0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
115b0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
115c0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
115d0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
115e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
115f0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11600 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11610 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11620 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11630 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11640 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11650 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11660 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11670 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11680 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11690 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
116a0 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
116b0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
116c0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
116d0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
116e0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
116f0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
11700 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
11710 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
11720 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
11730 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
117a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
117b0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
117c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
117d0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
117e0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
117f0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
11800 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11810 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
11820 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
11830 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11840 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
11850 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
11860 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11870 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11890 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
118a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
118b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
118c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
118d0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
118e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
118f0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11900 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11910 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11920 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
11930 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11940 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
11950 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
11960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11970 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11980 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11990 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
119a0 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
119b0 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
119c0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
119d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
119e0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
119f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11a00 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
11a10 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
11a20 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
11a30 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
11a40 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
11a50 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
11a60 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
11a70 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
11a80 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
11a90 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
11aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ab0 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
11ac0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
11ad0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ae0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11af0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11b00 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11b10 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11b20 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11b30 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11b40 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11b50 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
11b60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
11b70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
11b80 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11b90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11ba0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11bb0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
11bc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11bd0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
11be0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11bf0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11c00 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
11c10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c20 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
11c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11c40 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11c50 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11c60 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
11c70 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
11c80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
11c90 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
11ca0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
11cb0 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
11cc0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
11cd0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
11ce0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
11cf0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
11d00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
11d10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11d20 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
11d30 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
11d40 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
11d50 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
11d60 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11d70 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
11d80 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
11d90 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
11da0 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
11db0 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
11dc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11dd0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
11de0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
11df0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
11e00 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
11e10 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
11e20 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
11e30 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
11e40 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
11e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
11e60 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
11e70 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
11e80 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
11e90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ea0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11eb0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11ec0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ed0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11ee0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11ef0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11f00 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
11f10 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
11f20 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11f40 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11f50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11f60 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11f70 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11f80 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
11f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11fa0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11fb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11fc0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
11fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
11fe0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
11ff0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12000 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12010 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12020 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12030 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12040 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12050 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12060 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
12070 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12080 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12090 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
120a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
120b0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
120c0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
120d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
120e0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
120f0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12100 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12110 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12120 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12130 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12140 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12150 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12160 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12170 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
12180 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
12190 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
121a0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
121b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
121c0 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
121d0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
121e0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
121f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12200 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12210 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12220 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12230 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12240 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
12250 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12260 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12270 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12280 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12290 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
122a0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
122b0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
122c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
122d0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
122e0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12300 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12310 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12320 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12330 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12340 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12350 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12360 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12370 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12380 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12390 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
123a0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
123b0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
123c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
123d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
123e0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
123f0 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f  eted as a .** bo
12400 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
12410 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
12420 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
12430 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
12440 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74  tion .** statist
12450 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
12460 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12470 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12480 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66  abled, the .** f
12490 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
124a0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
124b0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
124c0 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
124d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
124e0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
124f0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12500 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
12510 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
12520 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
12530 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
12540 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12550 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
12560 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
12570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12580 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
12590 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
125a0 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
125b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
125c0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
125d0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
125e0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
125f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
12600 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12610 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
12620 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
12630 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12640 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
12650 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12660 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
12670 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12680 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12690 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
126a0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
126b0 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
126c0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
126d0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
126e0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
126f0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
12700 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
12710 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
12720 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
12730 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
12740 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
12750 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
12760 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12770 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
12780 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
12790 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
127a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
127b0 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
127c0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
127d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
127e0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
127f0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
12800 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12810 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12820 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
12830 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  se more than two
12840 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
12850 20 70 65 72 20 74 68 72 65 61 64 20 61 6e 64 20   per thread and 
12860 6e 6f 74 0a 2a 2a 20 6d 6f 72 65 20 74 68 61 6e  not.** more than
12870 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
12880 66 65 72 20 70 65 72 20 74 68 72 65 61 64 20 77  fer per thread w
12890 68 65 6e 20 6e 6f 74 20 70 65 72 66 6f 72 6d 69  hen not performi
128a0 6e 67 0a 2a 2a 20 61 20 5b 63 68 65 63 6b 70 6f  ng.** a [checkpo
128b0 69 6e 74 5d 20 69 6e 20 5b 57 41 4c 20 6d 6f 64  int] in [WAL mod
128c0 65 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  e]..** ^SQLite w
128d0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
128e0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
128f0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
12900 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
12910 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12920 65 20 73 69 7a 65 2c 20 65 78 63 65 70 74 20 77  e size, except w
12930 68 65 6e 20 70 65 72 66 6f 72 6d 69 6e 67 20 61  hen performing a
12940 20 5b 63 68 65 63 6b 70 6f 69 6e 74 5d 0a 2a 2a   [checkpoint].**
12950 20 69 6e 20 5b 57 41 4c 20 6d 6f 64 65 5d 20 77   in [WAL mode] w
12960 68 65 6e 20 74 68 65 20 73 63 72 61 74 63 68 20  hen the scratch 
12970 62 75 66 66 65 72 20 72 65 71 75 65 73 74 20 73  buffer request s
12980 69 7a 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 66  ize is a small f
12990 72 61 63 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  raction.** of th
129a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 57 41  e size of the WA
129b0 4c 20 66 69 6c 65 2e 0a 2a 2a 20 5e 49 66 20 53  L file..** ^If S
129c0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
129d0 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
129e0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
129f0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12a00 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12a10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12a20 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
12a30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12a40 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
12a50 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
12a60 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
12a70 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
12a80 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
12a90 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
12aa0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
12ab0 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
12ac0 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
12ad0 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
12ae0 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
12af0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
12b00 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
12b10 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
12b20 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
12b30 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
12b40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12b50 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
12b60 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
12b70 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
12b80 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
12b90 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
12ba0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12bb0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
12bc0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12bd0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
12be0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12bf0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12c00 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12c10 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12c20 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12c30 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12c40 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
12c50 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
12c60 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12c70 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
12c80 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
12c90 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
12ca0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
12cb0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
12cc0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12cd0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
12ce0 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
12cf0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
12d00 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
12d10 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12d20 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12d30 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
12d40 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
12d50 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
12d60 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
12d70 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
12d80 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
12d90 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
12da0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
12db0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
12dc0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
12dd0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
12de0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
12df0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
12e00 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
12e10 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
12e20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
12e30 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
12e40 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
12e50 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
12e60 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
12e70 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
12e80 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
12e90 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
12ea0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
12eb0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
12ec0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
12ed0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
12ee0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
12ef0 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
12f00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
12f10 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12f20 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12f30 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12f40 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
12f50 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
12f60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
12f70 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
12f80 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
12f90 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
12fa0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
12fb0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
12fc0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
12fd0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
12fe0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
12ff0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
13000 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
13010 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
13020 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
13030 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
13040 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
13050 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
13060 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
13070 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13080 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
13090 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
130a0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
130b0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
130c0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
130d0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
130e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
130f0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
13100 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13110 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
13120 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
13130 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13140 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13150 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
13160 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
13170 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
13180 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
13190 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
131a0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
131b0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
131c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
131d0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
131e0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
131f0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
13200 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
13210 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
13220 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
13230 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
13240 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
13250 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
13260 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
13270 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13280 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
13290 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
132a0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
132b0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
132c0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
132d0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
132e0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
132f0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
13300 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
13310 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
13320 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
13330 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
13340 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
13350 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
13360 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
13370 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
13380 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
13390 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
133a0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
133b0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
133c0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
133d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
133e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
133f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
13400 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
13410 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
13420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13430 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
13440 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
13450 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13460 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
13470 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
13480 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
13490 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
134a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
134b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
134c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
134d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
134e0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
134f0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
13500 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
13510 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13520 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
13530 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
13540 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13550 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
13560 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13570 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
13580 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13590 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
135a0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
135b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
135c0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
135d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
135e0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
135f0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
13600 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
13610 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
13620 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
13630 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13640 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
13650 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
13660 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
13670 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
13680 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
13690 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
136a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
136b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
136c0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
136d0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
136e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
136f0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
13700 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13710 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13720 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13730 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13740 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13750 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13760 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13770 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13780 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13790 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
137a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
137b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
137c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
137d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
137e0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
137f0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13800 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13810 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13820 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13830 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
13840 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13850 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
13860 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13870 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13880 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13890 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
138a0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
138b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
138c0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
138d0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
138e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
138f0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13900 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13910 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13920 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
13930 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
13940 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13950 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13960 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13970 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
13980 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
13990 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
139a0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
139b0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
139c0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
139d0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
139e0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
139f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13a00 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13a10 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13a20 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13a30 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13a40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13a50 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
13a60 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
13a70 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
13a80 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
13a90 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
13aa0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13ab0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
13ac0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13ad0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
13ae0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13af0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13b00 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13b10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13b20 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13b30 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13b40 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13b50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13b60 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13b70 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
13b80 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
13b90 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
13ba0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13bb0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
13bc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13bd0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
13be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13bf0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
13c00 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13c10 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13c20 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
13c30 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
13c40 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
13c50 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
13c60 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
13c70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13c80 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
13c90 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13ca0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
13cb0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
13cc0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
13cd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13ce0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
13cf0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
13d00 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
13d10 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13d20 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
13d30 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
13d40 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
13d50 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
13d60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13d70 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
13d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13d90 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
13da0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13db0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13dc0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13dd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
13de0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
13df0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
13e00 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
13e10 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
13e20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
13e30 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
13e40 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13e50 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
13e60 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
13e70 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
13e80 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
13e90 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
13ea0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
13eb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13ec0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13ed0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
13ee0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
13ef0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13f00 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13f10 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13f20 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13f30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
13f40 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13f50 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13f60 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
13f70 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
13f80 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
13f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
13fa0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
13fb0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13fd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13fe0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
13ff0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14000 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14010 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
14020 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14030 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
14040 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
14050 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14060 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
14070 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
14080 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
14090 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
140a0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
140b0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
140c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
140d0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
140e0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
140f0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
14100 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
14110 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
14120 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14130 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
14140 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
14150 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
14160 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
14170 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
14180 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
14190 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
141a0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
141b0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
141c0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
141d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
141e0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
141f0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
14200 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
14210 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14220 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14230 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14240 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14250 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14260 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14270 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14280 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14290 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
142a0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
142b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
142c0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
142d0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
142e0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
142f0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
14300 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
14310 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
14320 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14330 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14340 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14350 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14360 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14370 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14380 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14390 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
143a0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
143b0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
143c0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
143d0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
143e0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
143f0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
14400 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
14410 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
14420 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14430 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14440 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14450 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14460 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14470 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14480 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14490 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
144a0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
144b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
144c0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
144d0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
144e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
144f0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
14500 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
14510 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
14520 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
14530 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
14540 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
14550 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14560 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
14570 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
14580 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14590 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
145a0 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
145b0 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73  .** passed to [s
145c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
145d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
145e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
145f0 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
14600 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
14610 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
14620 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
14630 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
14640 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
14650 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14660 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
14670 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
14680 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
14690 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
146a0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
146b0 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
146c0 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
146d0 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
146e0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
146f0 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
14700 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
14710 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
14720 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14730 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
14740 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
14750 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
14760 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
14770 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
14780 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
14790 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
147a0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
147b0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
147c0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
147d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
147e0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
147f0 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
14800 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
14810 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14820 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20  AN.** <dd>^This 
14830 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14840 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72  ingle integer ar
14850 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14860 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a  interpreted as.*
14870 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  * a boolean in o
14880 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
14890 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  r disable the us
148a0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
148b0 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c  dices for.** ful
148c0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
148d0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
148e0 69 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61  izer.  ^The defa
148f0 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
14900 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
14910 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
14920 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
14930 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
14940 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
14950 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
14960 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
14970 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
14980 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
14990 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
149a0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
149b0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
149c0 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
149d0 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
149e0 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
149f0 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
14a00 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
14a10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
14a20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14a30 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
14a40 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
14a50 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
14a60 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
14a70 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
14a80 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
14a90 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
14aa0 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
14ab0 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
14ac0 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
14ad0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
14ae0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14af0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
14b00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14b10 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
14b20 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14b30 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
14b40 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
14b50 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
14b60 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
14b70 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
14b80 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
14b90 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
14ba0 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
14bb0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
14bc0 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
14bd0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
14be0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
14c00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14c10 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
14c20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
14c30 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
14c40 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
14c50 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
14c60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
14c70 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
14c80 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
14c90 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
14ca0 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
14cb0 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
14cc0 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
14cd0 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
14ce0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
14cf0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
14d00 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
14d10 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
14d20 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
14d30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
14d40 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
14d50 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
14d60 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
14d70 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
14d80 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
14d90 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
14da0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
14db0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
14dc0 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
14dd0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
14df0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
14e00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
14e10 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
14e20 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
14e30 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
14e40 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
14e50 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
14e60 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
14e70 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
14e80 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
14e90 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
14ea0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14eb0 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
14ec0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
14ed0 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
14ee0 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
14ef0 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
14f00 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14f10 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
14f20 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
14f30 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
14f40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
14f50 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
14f60 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
14f70 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
14f80 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
14f90 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
14fa0 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
14fb0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14fc0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
14fd0 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
14fe0 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
14ff0 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15000 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15010 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15020 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15030 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15040 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15050 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15060 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
15070 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15080 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
15090 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
150a0 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
150b0 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
150c0 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
150d0 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
150e0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
150f0 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
15100 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
15110 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15120 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15130 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15140 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15150 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15160 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15170 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
15180 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
15190 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
151a0 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
151b0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
151c0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
151d0 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
151e0 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
151f0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15200 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  size.** cannot b
15210 65 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e  e changed at run
15220 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20  -time.  Nor may 
15230 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
15240 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
15250 20 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70   exceed the comp
15260 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
15270 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
15280 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15290 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
152a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
152b0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
152c0 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
152d0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
152e0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
152f0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
15300 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
15310 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
15320 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
15330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15340 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
15350 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15360 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15370 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20  ZE.** <dd>^This 
15380 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15390 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
153a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  te is compiled f
153b0 6f 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69  or Windows.** wi
153c0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
153d0 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
153e0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
153f0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c   defined..** SQL
15400 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15410 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20  _HEAPSIZE takes 
15420 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 32-bit unsigne
15430 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a  d integer value.
15440 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65  ** that specifie
15450 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  s the maximum si
15460 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65  ze of the create
15470 64 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e  d heap..** </dl>
15480 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
15490 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
154a0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
154b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
154c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
154d0 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
154e0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
154f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
15500 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
15510 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
15520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15530 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
15540 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
15550 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
15560 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15570 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
15580 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
15590 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
155a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
155b0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
155c0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
155d0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
155e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
155f0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
15600 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
15610 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
15620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15630 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
15640 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
15650 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
15660 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
15670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
15680 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
15690 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
156a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
156b0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
156c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
156d0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
156e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
156f0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
15700 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
15710 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15720 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
15730 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
15740 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
15750 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
15760 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
15770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
15780 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
15790 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
157a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
157b0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
157c0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
157d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
157e0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
157f0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
15800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15810 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
15820 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
15830 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
15840 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15850 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
15860 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
15870 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15880 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
15890 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
158a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
158b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
158c0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
158d0 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
158e0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
158f0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15900 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15910 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15920 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
15930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15940 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
15950 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
15960 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
15970 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15980 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
15990 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
159a0 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
159b0 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
159c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
159d0 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
159e0 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
159f0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
15a00 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
15a10 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
15a20 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
15a30 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
15a40 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
15a50 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
15a60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15a70 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
15a80 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
15a90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15aa0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
15ab0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
15ac0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
15ad0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
15ae0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
15af0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
15b00 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
15b10 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
15b20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15b30 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
15b40 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
15b50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
15b60 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
15b70 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
15b80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15b90 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
15ba0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
15bb0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
15bc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
15bd0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
15be0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
15bf0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
15c00 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
15c10 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
15c20 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
15c30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
15c40 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
15c50 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
15c60 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15c70 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
15c80 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15c90 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
15ca0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
15cb0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15cc0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
15cd0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
15ce0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
15cf0 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
15d00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15d10 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
15d20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
15d30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15d40 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
15d50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
15d60 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15d70 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
15d80 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
15d90 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
15da0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15db0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
15dc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15dd0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
15de0 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
15df0 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
15e00 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
15e10 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
15e20 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
15e30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
15e40 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
15e50 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
15e60 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
15e70 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
15e80 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
15e90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
15ea0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
15eb0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
15ec0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
15ed0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
15ee0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
15ef0 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
15f00 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
15f10 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
15f20 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
15f30 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
15f40 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
15f50 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
15f60 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
15f70 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
15f80 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
15f90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15fa0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
15fb0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
15fc0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
15fd0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
15fe0 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
15ff0 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16000 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16010 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16020 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16030 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16040 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16050 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16060 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
16070 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
16080 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
16090 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
160a0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
160b0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
160c0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
160d0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
160e0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
160f0 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16100 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16110 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16120 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16130 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16140 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16150 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16160 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
16170 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
16180 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
16190 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
161a0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
161b0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
161c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
161d0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
161e0 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
161f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16200 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16210 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16220 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16230 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16240 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16250 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16260 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16270 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16280 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16290 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
162a0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
162b0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
162c0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
162d0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
162e0 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
162f0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
16300 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
16310 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
16320 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16330 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16340 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16350 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16360 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16370 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16380 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
16390 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
163a0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
163b0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
163c0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
163d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
163e0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
163f0 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
16400 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
16410 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
16420 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
16430 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16440 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
16450 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
16460 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16470 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16480 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
16490 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
164a0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
164b0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
164c0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
164d0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
164e0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
164f0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
16500 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
16510 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
16520 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
16530 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
16540 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
16550 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
16560 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
16570 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
16580 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
16590 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
165a0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
165b0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
165c0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
165d0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
165e0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
165f0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
16600 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16610 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
16620 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
16630 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16640 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
16650 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16660 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16670 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
16680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
16690 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
166a0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
166b0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
166c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
166d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
166e0 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
166f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
16700 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16710 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
16720 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
16730 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
16740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
16750 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
16760 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
16770 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
16780 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
16790 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
167a0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
167b0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
167c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
167d0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
167e0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
167f0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
16800 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
16810 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
16820 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
16830 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
16840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
16850 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
16860 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
16870 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
16880 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
16890 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
168a0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
168b0 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
168c0 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
168d0 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
168e0 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
168f0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
16900 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
16910 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
16920 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
16930 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
16940 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
16950 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
16960 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
16970 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
16980 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
16990 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
169a0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
169b0 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
169c0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
169d0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
169e0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
169f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
16a00 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
16a10 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
16a20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
16a30 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
16a40 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
16a50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
16a60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
16a70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
16a80 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
16a90 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
16aa0 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
16ab0 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
16ac0 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
16ad0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
16ae0 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
16af0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
16b00 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
16b10 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
16b20 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
16b30 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
16b40 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
16b50 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
16b60 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
16b70 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
16b80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
16b90 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
16ba0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
16bb0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16bc0 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
16bd0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
16be0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
16bf0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
16c00 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
16c10 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
16c20 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
16c30 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
16c40 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
16c50 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
16c60 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
16c70 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
16c80 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16c90 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
16ca0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
16cb0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
16cc0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
16cd0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
16ce0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
16cf0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
16d00 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
16d10 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
16d20 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
16d30 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
16d40 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
16d50 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
16d60 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
16d70 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
16d80 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
16d90 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
16da0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
16db0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
16dc0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16dd0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
16de0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
16df0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
16e00 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
16e10 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
16e20 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
16e30 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
16e40 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
16e50 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
16e60 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
16e70 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
16e80 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
16e90 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
16ea0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
16eb0 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
16ec0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
16ed0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
16ee0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
16ef0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
16f00 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
16f10 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
16f20 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
16f30 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
16f40 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
16f50 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
16f60 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
16f70 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
16f80 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
16f90 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
16fa0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
16fb0 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
16fc0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
16fd0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
16fe0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
16ff0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
17000 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
17010 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
17020 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
17030 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
17040 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
17050 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17060 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17070 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17080 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
17090 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
170a0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
170b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
170c0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
170d0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
170e0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
170f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
17100 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
17110 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
17120 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
17130 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
17140 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
17150 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17160 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
17170 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
17180 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
17190 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
171a0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
171b0 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
171c0 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
171d0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
171e0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
171f0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
17200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17210 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
17220 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
17230 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
17240 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17250 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
17260 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
17270 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
17280 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
17290 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
172a0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
172b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
172c0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
172d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
172e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
172f0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
17300 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
17310 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
17320 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
17330 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
17340 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
17350 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
17360 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
17370 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
17380 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
17390 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
173a0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
173b0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
173c0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
173d0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
173e0 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
173f0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
17400 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
17410 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
17420 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
17430 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
17440 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
17450 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
17460 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
17470 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
17480 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
17490 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
174a0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
174b0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
174c0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
174d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
174e0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
174f0 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
17500 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
17510 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
17520 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
17530 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
17540 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
17550 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
17560 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
17570 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
17580 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
17590 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
175a0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
175b0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
175c0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
175d0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
175e0 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
175f0 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
17600 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
17610 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
17620 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
17630 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
17640 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
17650 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
17660 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
17670 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
17680 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
17690 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
176a0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
176b0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
176c0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
176d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
176e0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
176f0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
17700 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
17710 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
17720 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
17730 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
17740 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
17750 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
17760 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
17770 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
17780 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
17790 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
177a0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
177b0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
177c0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
177d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
177e0 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
177f0 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
17800 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
17810 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
17820 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
17830 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
17840 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
17850 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
17860 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
17870 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17880 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
17890 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
178a0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
178b0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
178c0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
178d0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
178e0 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
178f0 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
17900 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
17910 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
17920 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
17930 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
17940 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
17950 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
17960 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
17970 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
17980 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
17990 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
179a0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
179b0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
179c0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
179d0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
179e0 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
179f0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
17a00 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
17a10 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17a20 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
17a30 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
17a40 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
17a50 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
17a60 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
17a70 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
17a80 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
17a90 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
17aa0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17ab0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17ac0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17ad0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17ae0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17af0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17b00 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17b10 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17b20 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17b30 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17b40 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17b50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17b60 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
17b70 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17b80 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17b90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17ba0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17bb0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17bc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17bd0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17be0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17bf0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
17c00 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17c10 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17c20 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17c30 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
17c40 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
17c50 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
17c60 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
17c70 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
17c80 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
17c90 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
17ca0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
17cb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17cc0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
17cd0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
17ce0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
17cf0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
17d00 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
17d10 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
17d20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
17d30 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
17d40 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
17d50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
17d60 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17d70 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
17d80 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
17d90 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
17da0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
17db0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
17dc0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
17dd0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
17de0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
17df0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
17e00 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
17e10 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
17e20 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
17e30 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
17e40 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
17e50 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
17e60 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
17e70 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
17e80 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
17e90 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
17ea0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
17eb0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
17ec0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
17ed0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
17ee0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
17ef0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
17f00 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
17f10 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
17f20 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
17f30 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
17f40 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17f50 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17f60 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
17f70 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17f80 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17f90 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
17fa0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17fb0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17fc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
17fd0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
17fe0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
17ff0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18000 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
18010 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
18020 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
18030 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
18040 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
18050 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
18060 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
18070 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
18080 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
18090 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
180a0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
180b0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
180c0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
180d0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
180e0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
180f0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
18100 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
18110 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
18120 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
18130 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
18140 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
18150 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
18160 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
18170 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
18180 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
18190 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
181a0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
181b0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
181c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
181d0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
181e0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
181f0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
18200 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18210 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
18220 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
18230 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
18240 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
18250 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
18260 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18270 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
18280 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
18290 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
182a0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
182b0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
182c0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
182d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
182e0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
182f0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
18300 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
18310 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
18320 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
18330 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
18340 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
18350 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
18360 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
18370 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
18380 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
18390 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
183a0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
183b0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
183c0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
183d0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
183e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
183f0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
18400 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
18410 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
18420 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
18430 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
18440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18450 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
18460 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
18470 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18480 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18490 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
184a0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
184b0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
184c0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
184d0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
184e0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
184f0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
18500 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
18510 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
18520 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18530 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
18540 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
18550 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
18560 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
18570 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
18580 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
18590 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
185a0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
185b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
185c0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
185d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
185e0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
185f0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
18600 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
18610 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
18620 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
18630 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
18640 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18650 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18660 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
18670 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18680 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
18690 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
186a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
186b0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
186c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
186d0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
186e0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
186f0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
18700 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
18710 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
18720 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
18730 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
18740 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
18750 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
18760 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18770 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
18780 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
18790 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
187a0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
187b0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
187c0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
187d0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
187e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
187f0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
18800 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
18810 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
18820 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
18830 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
18840 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
18850 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18860 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
18870 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
18880 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
18890 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
188a0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
188b0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
188c0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
188d0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
188e0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
188f0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
18900 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
18910 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
18920 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
18930 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
18940 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
18950 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
18960 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
18970 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
18980 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
18990 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
189a0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
189b0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
189c0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
189d0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
189e0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
189f0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
18a00 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
18a10 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
18a20 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
18a30 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
18a40 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
18a50 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
18a60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
18a70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18a80 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
18a90 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
18aa0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
18ab0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
18ac0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
18ad0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
18ae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
18af0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
18b00 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
18b10 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
18b20 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
18b30 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
18b40 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
18b50 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
18b60 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
18b70 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
18b80 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
18b90 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
18ba0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
18bb0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18bc0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
18bd0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
18be0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
18bf0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
18c00 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
18c10 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
18c20 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
18c30 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
18c40 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
18c50 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18c60 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
18c70 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
18c80 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
18c90 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
18ca0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
18cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
18cc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
18cd0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
18ce0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
18cf0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
18d00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
18d10 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
18d20 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
18d30 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
18d40 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
18d50 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
18d60 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
18d70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
18d80 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
18d90 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
18da0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18db0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
18dc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18dd0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
18de0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
18df0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
18e00 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ors.**.** ^The s
18e10 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18e20 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
18e30 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
18e40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
18e50 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
18e60 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
18e70 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
18e80 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
18e90 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
18ea0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18eb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
18ec0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
18ed0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
18ee0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
18ef0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
18f00 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
18f10 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
18f20 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18f30 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
18f40 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
18f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
18f60 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
18f70 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
18f80 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
18f90 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
18fa0 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
18fb0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
18fc0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
18fd0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
18fe0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
18ff0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
19000 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
19010 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
19020 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
19030 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
19040 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
19050 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
19060 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
19070 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
19080 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
19090 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
190a0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
190b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
190c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
190d0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
190e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
190f0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
19100 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
19110 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
19120 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
19130 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
19140 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
19150 65 64 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ed for the same 
19160 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
19170 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
19180 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19190 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
191a0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
191b0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
191c0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
191d0 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
191e0 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
191f0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
19200 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
19210 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
19220 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
19230 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
19240 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
19250 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
19260 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
19270 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
19280 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
19290 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
192a0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
192b0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
192c0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
192d0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
192e0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
192f0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
19300 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
19310 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
19320 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
19330 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
19340 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
19350 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
19360 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
19370 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
19380 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
19390 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
193a0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
193b0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
193c0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
193d0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
193e0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
193f0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
19400 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
19410 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
19420 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
19430 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
19440 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
19450 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
19460 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
19470 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
19480 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
19490 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
194a0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
194b0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
194c0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
194d0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
194e0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
194f0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
19500 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
19510 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
19520 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
19530 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
19540 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
19550 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
19560 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
19570 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
19580 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
19590 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
195a0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
195b0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
195c0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
195d0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
195e0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
195f0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
19600 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
19610 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
19620 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
19630 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
19640 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
19650 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19660 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19670 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19680 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
19690 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
196a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
196b0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
196c0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
196d0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
196e0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
196f0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
19700 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
19710 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
19720 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
19730 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
19740 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
19750 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
19760 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
19770 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
19780 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
19790 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
197a0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
197b0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
197c0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
197d0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
197e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
197f0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19800 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19810 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
19820 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
19830 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
19840 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
19850 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
19860 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
19870 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
19880 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
19890 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
198a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
198b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
198c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
198d0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
198e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
198f0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
19900 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
19910 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
19920 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
19930 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19940 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
19950 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
19960 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
19970 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
19980 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
19990 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
199a0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
199b0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
199c0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
199d0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
199e0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
199f0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
19a00 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
19a10 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
19a20 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
19a30 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
19a40 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
19a50 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
19a60 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19a70 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
19a80 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
19a90 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
19aa0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
19ab0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
19ac0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
19ad0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
19ae0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
19af0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
19b00 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
19b10 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
19b20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
19b30 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
19b40 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
19b50 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
19b60 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
19b70 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
19b80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19b90 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
19ba0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
19bb0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
19bc0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
19bd0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
19be0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
19bf0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
19c00 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
19c10 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
19c20 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
19c30 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
19c40 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
19c50 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
19c60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
19c70 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
19c80 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
19c90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19ca0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
19cb0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
19cc0 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
19cd0 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
19ce0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
19cf0 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
19d00 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
19d10 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
19d20 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
19d30 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
19d40 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
19d50 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
19d60 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
19d70 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
19d80 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
19d90 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19da0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
19db0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
19dc0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
19dd0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
19de0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
19df0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
19e00 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
19e10 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
19e20 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
19e30 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
19e40 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
19e50 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
19e60 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
19e70 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
19e80 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
19e90 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
19ea0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
19eb0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
19ec0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
19ed0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
19ee0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
19ef0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
19f00 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
19f10 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
19f20 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
19f30 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
19f40 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
19f50 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
19f60 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
19f70 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
19f80 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
19f90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
19fa0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
19fb0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
19fc0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
19fd0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
19fe0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
19ff0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1a000 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1a010 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1a020 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1a030 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1a040 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1a050 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1a060 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1a070 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1a080 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1a090 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1a0a0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1a0b0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1a0c0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1a0d0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1a0e0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1a0f0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1a100 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1a110 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1a120 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1a130 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a140 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1a150 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1a160 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a170 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1a180 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1a190 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a1a0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1a1b0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1a1c0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1a1d0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a1e0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1a1f0 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1a200 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1a210 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a220 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1a230 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1a240 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1a250 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1a260 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1a270 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1a280 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1a290 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1a2a0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1a2b0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1a2c0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1a2d0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1a2e0 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1a2f0 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1a300 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1a310 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1a320 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1a330 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1a340 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1a350 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1a360 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a370 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a380 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1a390 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a3a0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1a3b0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1a3c0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1a3d0 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1a3e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a3f0 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1a400 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a410 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1a420 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a430 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1a440 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a450 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1a460 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1a470 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1a480 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1a490 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1a4a0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1a4b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a4c0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1a4d0 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1a4e0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1a4f0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1a500 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1a510 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a520 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1a530 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1a540 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1a550 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1a560 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1a570 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1a580 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1a590 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1a5a0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1a5b0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1a5c0 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1a5d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1a5e0 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1a5f0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1a600 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1a610 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1a620 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1a630 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1a640 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1a650 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1a660 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1a670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a680 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1a690 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a6a0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1a6b0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1a6c0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1a6d0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1a6e0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1a6f0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1a700 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1a710 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1a720 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1a730 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1a740 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a750 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1a760 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1a770 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1a780 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1a790 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1a7a0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1a7b0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1a7c0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1a7d0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1a7e0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1a7f0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1a800 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1a810 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1a820 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1a830 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1a840 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1a850 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1a860 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1a870 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1a880 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1a890 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1a8a0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1a8b0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1a8c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1a8d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1a8e0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1a8f0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1a900 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1a910 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1a920 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1a930 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1a940 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1a950 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1a960 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1a970 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1a980 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1a990 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1a9a0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1a9b0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1a9c0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1a9d0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1a9e0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1a9f0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1aa00 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1aa10 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1aa20 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1aa30 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1aa40 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1aa50 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1aa60 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1aa70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1aa80 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1aa90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1aaa0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1aab0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1aac0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1aad0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1aae0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1aaf0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1ab00 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1ab10 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1ab20 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1ab30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ab40 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1ab50 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1ab60 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1ab70 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1ab80 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1ab90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1aba0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1abb0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1abc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1abd0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1abe0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1abf0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1ac00 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1ac10 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1ac20 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1ac30 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1ac40 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1ac50 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1ac60 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1ac70 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1ac80 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1ac90 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1aca0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1acb0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1acc0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1acd0 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1ace0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1acf0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ad00 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ad10 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1ad20 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1ad30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1ad40 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1ad50 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1ad60 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1ad70 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1ad80 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1ad90 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1ada0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1adb0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1adc0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1add0 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1ade0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1adf0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1ae00 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1ae10 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1ae20 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1ae30 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1ae40 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1ae50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1ae60 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1ae70 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1ae80 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1ae90 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1aea0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1aeb0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1aec0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1aed0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1aee0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1aef0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1af00 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1af10 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1af20 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1af30 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1af40 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1af50 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1af60 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1af70 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1af80 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1af90 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1afa0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1afb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1afc0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1afd0 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1afe0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1aff0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1b000 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1b010 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1b020 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1b030 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1b040 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1b050 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1b060 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1b070 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1b080 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1b090 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1b0a0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1b0b0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1b0c0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1b0d0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1b0e0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1b0f0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1b100 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1b110 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1b120 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1b130 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1b140 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1b150 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1b160 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1b170 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1b180 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1b190 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1b1a0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1b1b0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1b1c0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1b1d0 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1b1e0 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
1b1f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1b200 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1b210 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1b220 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1b230 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1b240 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1b250 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1b260 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1b270 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1b280 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1b290 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1b2a0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1b2b0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1b2c0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1b2d0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1b2e0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1b2f0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1b300 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1b310 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1b320 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1b330 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1b340 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1b350 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1b360 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1b370 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1b380 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b390 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1b3a0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1b3b0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1b3c0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1b3d0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1b3e0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1b3f0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1b400 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1b410 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b420 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1b430 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1b440 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1b450 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1b460 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1b470 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1b480 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1b490 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1b4a0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1b4b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b4c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1b4d0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1b4e0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1b4f0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1b500 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1b510 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1b520 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1b530 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1b540 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1b550 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1b560 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1b570 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1b580 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1b590 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b5a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1b5b0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1b5c0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1b5d0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1b5e0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1b5f0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1b600 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1b610 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b620 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1b630 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1b640 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1b650 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1b660 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b670 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1b680 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1b690 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1b6a0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1b6b0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1b6c0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1b6d0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1b6e0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1b6f0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1b700 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1b710 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1b720 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1b730 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1b740 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1b750 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1b760 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1b770 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1b780 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1b790 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1b7a0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1b7b0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1b7c0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1b7d0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1b7e0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1b7f0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1b800 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1b810 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1b820 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1b830 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b840 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1b850 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1b860 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1b870 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1b880 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1b890 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1b8a0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1b8b0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1b8c0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1b8d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b8e0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1b8f0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1b900 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1b910 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1b920 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1b930 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1b940 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1b950 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1b960 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1b970 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1b980 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1b990 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1b9a0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1b9b0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1b9c0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1b9d0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1b9e0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1b9f0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1ba00 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1ba10 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1ba20 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1ba30 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1ba40 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1ba50 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1ba60 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1ba70 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1ba80 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1ba90 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1baa0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1bab0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1bac0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1bad0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1bae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1baf0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1bb00 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1bb10 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1bb20 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1bb30 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1bb40 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1bb50 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1bb60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1bb70 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1bb80 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1bb90 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1bba0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1bbb0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1bbc0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1bbd0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1bbe0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1bbf0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1bc00 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1bc10 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1bc20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bc30 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1bc40 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1bc50 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1bc60 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1bc70 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1bc80 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1bc90 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1bca0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1bcb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1bcc0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1bcd0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1bce0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1bcf0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1bd00 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1bd10 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1bd20 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bd30 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1bd40 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1bd50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1bd60 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1bd70 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1bd80 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1bd90 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1bda0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1bdb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bdc0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1bdd0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1bde0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1bdf0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1be00 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1be10 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1be20 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1be30 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1be40 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1be50 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1be60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1be70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1be80 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1be90 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1bea0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1beb0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1bec0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1bed0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1bee0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1bef0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1bf00 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1bf10 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1bf20 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1bf30 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1bf40 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1bf50 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1bf60 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1bf70 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1bf80 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1bf90 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1bfa0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1bfb0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1bfc0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1bfd0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1bfe0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1bff0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1c000 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1c010 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c020 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1c030 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1c040 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1c050 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1c060 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1c070 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1c080 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1c090 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1c0a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1c0b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c0c0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1c0d0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1c0e0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1c0f0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1c100 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1c110 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1c120 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1c130 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c140 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c150 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1c160 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1c170 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1c180 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1c190 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1c1a0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1c1b0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1c1c0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1c1d0 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1c1e0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1c1f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1c200 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1c210 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1c220 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1c230 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1c240 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1c250 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c260 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1c270 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1c280 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1c290 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1c2a0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1c2b0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1c2c0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1c2d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1c2e0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1c2f0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1c300 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1c310 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1c320 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1c330 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1c340 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1c350 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1c360 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1c370 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c380 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1c390 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1c3a0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1c3b0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1c3c0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1c3d0 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1c3e0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1c3f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1c400 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1c410 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1c420 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1c430 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1c440 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1c450 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1c460 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1c470 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1c480 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1c490 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1c4a0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1c4b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c4c0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1c4d0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1c4e0 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1c4f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1c500 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1c510 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1c520 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1c530 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1c540 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1c550 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1c560 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c570 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1c580 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c590 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1c5a0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1c5b0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1c5c0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1c5d0 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1c5e0 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1c5f0 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1c600 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1c610 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1c620 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1c630 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1c640 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1c650 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1c660 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1c670 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1c680 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1c690 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1c6a0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1c6b0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1c6c0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1c6d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1c6e0 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1c6f0 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1c700 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1c710 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1c720 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1c730 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1c740 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1c750 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1c760 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c770 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1c780 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1c790 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1c7a0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1c7b0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1c7c0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1c7d0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1c7e0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1c7f0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1c800 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1c810 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1c820 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1c830 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1c840 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1c850 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1c860 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1c870 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1c880 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1c890 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1c8a0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1c8b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c8c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1c8d0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1c8e0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1c8f0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1c900 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1c910 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1c920 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1c930 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1c940 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1c950 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1c960 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1c970 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1c980 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1c990 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1c9a0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1c9b0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1c9c0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1c9d0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1c9e0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1c9f0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1ca00 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1ca10 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1ca20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1ca30 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1ca40 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1ca50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1ca60 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1ca70 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1ca80 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1ca90 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1caa0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1cab0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1cac0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1cad0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1cae0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1caf0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1cb00 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1cb10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1cb20 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1cb30 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1cb40 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1cb50 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1cb60 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1cb70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
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 20 74 68 61 74 20 68  ealloc()] that h
1cba0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1cbb0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1cbc0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1cbd0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1cbe0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1cbf0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1cc00 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1cc10 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1cc20 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1cc30 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1cc40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1cc50 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1cc60 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1cc70 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1cc80 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1cc90 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1cca0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1ccb0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1ccc0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1ccd0 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1cce0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1ccf0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1cd00 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1cd10 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1cd20 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1cd30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cd50 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1cd60 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1cd70 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1cd80 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1cd90 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1cda0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1cdb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cdc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1cdd0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1cde0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1cdf0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1ce00 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1ce10 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1ce20 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1ce30 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1ce40 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1ce50 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1ce60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1ce70 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1ce80 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1ce90 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1cea0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1ceb0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1cec0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1ced0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1cee0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1cef0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1cf00 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cf10 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1cf20 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1cf30 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1cf40 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1cf50 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1cf60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1cf70 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1cf80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cf90 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1cfa0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1cfb0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1cfc0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1cfd0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1cfe0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1cff0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1d000 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1d010 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1d020 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1d030 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1d040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d050 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1d060 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1d070 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1d080 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1d090 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1d0a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1d0b0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1d0c0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1d0d0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1d0e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d0f0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1d100 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1d110 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1d120 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d130 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1d140 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1d150 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1d160 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1d170 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1d180 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1d190 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1d1a0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1d1b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1d1c0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1d1d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1d1e0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1d1f0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1d200 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1d210 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1d220 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1d230 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1d240 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1d250 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1d260 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1d270 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1d280 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1d290 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1d2a0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1d2b0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1d2c0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1d2d0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1d2e0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1d2f0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1d300 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1d310 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1d320 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1d330 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1d340 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1d350 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1d360 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1d370 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1d380 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1d390 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1d3a0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1d3b0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1d3c0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
1d3d0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
1d3e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d3f0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1d400 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1d410 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1d420 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1d430 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1d440 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
1d450 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1d460 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
1d470 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
1d480 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1d490 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
1d4a0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1d4b0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
1d4c0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d4d0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1d4e0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1d4f0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1d500 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1d510 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
1d520 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
1d530 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
1d540 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1d550 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1d560 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1d570 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1d580 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1d590 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1d5a0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1d5b0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1d5c0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1d5d0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1d5e0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1d5f0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1d600 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1d610 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1d620 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1d630 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d640 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1d650 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1d660 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1d670 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1d680 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1d690 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1d6a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1d6b0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1d6c0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1d6d0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1d6e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1d6f0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1d700 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1d710 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1d720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d730 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1d740 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1d750 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1d760 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1d770 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1d780 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1d790 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1d7a0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1d7b0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1d7c0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1d7d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1d7e0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1d7f0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1d800 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1d810 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d820 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1d830 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1d840 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1d850 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1d860 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1d870 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1d880 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1d890 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1d8a0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1d8b0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1d8c0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1d8d0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1d8e0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1d8f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1d900 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1d910 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1d920 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d930 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1d940 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1d950 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1d960 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1d970 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1d980 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1d990 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1d9a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1d9b0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1d9c0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1d9d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1d9e0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1d9f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1da00 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1da10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1da20 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1da30 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1da40 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1da50 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1da60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1da70 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1da80 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1da90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1daa0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1dab0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1dac0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1dad0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1dae0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1daf0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1db00 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1db10 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1db20 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1db30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1db40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1db50 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1db60 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1db70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1db80 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1db90 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1dba0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1dbb0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1dbc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1dbd0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1dbe0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1dbf0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1dc00 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1dc10 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1dc20 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1dc30 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1dc40 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1dc50 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1dc60 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1dc70 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1dc80 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1dc90 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1dca0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1dcb0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1dcc0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1dcd0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1dce0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1dcf0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1dd00 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1dd10 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1dd20 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1dd30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1dd40 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1dd50 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1dd60 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1dd70 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1dd80 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1dd90 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1dda0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1ddb0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1ddc0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1ddd0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1dde0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1ddf0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1de00 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1de10 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1de20 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1de30 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1de40 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1de50 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1de60 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1de70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1de80 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1de90 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1dea0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1deb0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1dec0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1ded0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1dee0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1def0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1df00 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1df10 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1df20 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1df30 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1df40 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1df50 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1df60 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1df70 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1df80 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1df90 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1dfa0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1dfb0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1dfc0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1dfd0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1dfe0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1dff0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1e000 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1e010 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1e020 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1e030 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1e040 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1e050 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1e060 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1e070 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1e080 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1e090 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1e0a0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1e0b0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1e0c0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1e0d0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1e0e0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1e0f0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1e100 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1e110 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1e120 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1e130 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1e140 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1e150 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1e160 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1e170 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1e180 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1e190 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1e1a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1e1b0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1e1c0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1e1d0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1e1e0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1e1f0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1e200 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1e210 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1e220 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1e230 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1e240 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1e250 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1e260 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1e270 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1e280 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1e290 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1e2a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1e2b0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1e2c0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1e2d0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1e2e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1e2f0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1e300 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1e310 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e320 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1e330 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1e340 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1e350 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1e360 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1e370 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1e380 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1e390 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1e3a0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1e3b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e3c0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1e3d0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1e3e0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1e3f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e400 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1e410 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e420 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1e430 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1e440 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1e450 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1e460 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1e470 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1e480 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1e490 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1e4a0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1e4b0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1e4c0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1e4d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1e4e0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1e4f0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1e500 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1e510 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1e520 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1e530 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1e540 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1e550 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1e560 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e570 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1e580 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1e590 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1e5a0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1e5b0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1e5c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1e5d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1e5e0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1e5f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e600 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1e610 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1e620 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1e630 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1e640 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1e650 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1e660 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1e670 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1e680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1e690 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1e6a0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1e6b0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1e6c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1e6d0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1e6e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1e6f0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1e700 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1e710 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1e720 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
1e730 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1e740 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1e750 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1e760 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1e770 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e780 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1e790 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1e7a0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1e7b0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e7c0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1e7d0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e7e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e7f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1e800 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1e810 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1e820 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1e830 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1e840 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1e850 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1e860 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1e870 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1e880 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1e890 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1e8a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1e8b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1e8c0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1e8d0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1e8e0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1e8f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1e900 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1e910 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1e920 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
1e930 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
1e940 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
1e950 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1e960 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1e970 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1e980 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e990 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1e9a0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1e9b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1e9c0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1e9d0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1e9e0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1e9f0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1ea00 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1ea10 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1ea20 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1ea30 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1ea40 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1ea50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ea60 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1ea70 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1ea80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1ea90 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1eaa0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1eab0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1eac0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1ead0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1eae0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1eaf0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1eb00 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1eb10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1eb20 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1eb30 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1eb40 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1eb50 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1eb60 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1eb70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1eb80 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1eb90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1eba0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1ebb0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1ebc0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1ebd0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1ebe0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1ebf0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1ec00 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1ec10 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1ec20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1ec30 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1ec40 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1ec50 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1ec60 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1ec70 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1ec80 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1ec90 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1eca0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1ecb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ecc0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1ecd0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1ece0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1ecf0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1ed00 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1ed10 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1ed20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ed30 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1ed40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1ed50 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1ed60 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1ed70 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1ed80 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1ed90 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1eda0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1edb0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1edc0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1edd0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1ede0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1edf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ee00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1ee10 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1ee20 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1ee30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ee40 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1ee50 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1ee60 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1ee70 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ee80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ee90 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1eea0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1eeb0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1eec0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1eed0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1eee0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1eef0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1ef00 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ef10 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ef20 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ef30 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1ef40 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1ef50 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ef60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ef70 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ef80 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1ef90 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1efa0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1efb0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1efc0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1efd0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1efe0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1eff0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f000 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f010 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f020 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1f030 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1f040 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1f050 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f060 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1f070 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1f080 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1f090 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f0a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f0b0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1f0c0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1f0d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f0e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f0f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f100 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1f110 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1f120 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f130 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f140 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f150 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1f160 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1f170 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f180 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f190 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f1a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1f1b0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1f1c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f1d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f1e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f1f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1f200 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1f210 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f220 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f240 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1f250 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1f260 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f270 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f280 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f290 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1f2a0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1f2b0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f2c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f2d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f2e0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1f2f0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1f300 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1f310 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f330 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1f340 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1f350 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1f360 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1f380 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1f390 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1f3a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f3b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f3c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1f3d0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1f3e0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1f3f0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1f400 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1f410 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1f420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f430 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1f440 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f450 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f460 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1f470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f480 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1f490 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f4a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f4b0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1f4c0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1f4d0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1f4e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f4f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f500 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1f510 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1f520 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f530 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f540 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f550 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1f560 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1f570 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1f580 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f590 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f5a0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1f5b0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1f5c0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1f5d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f5e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f5f0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1f600 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1f610 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f620 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f630 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f640 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1f650 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1f660 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f670 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f680 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f690 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1f6a0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1f6b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f6c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f6d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f6e0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1f6f0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1f700 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1f710 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1f720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f730 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1f740 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1f750 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f760 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f780 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1f790 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1f7a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1f7b0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1f7c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1f7d0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1f7e0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1f7f0 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1f800 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1f810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1f820 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1f830 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1f840 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
1f850 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
1f860 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
1f870 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
1f880 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1f890 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
1f8a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1f8b0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1f8c0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1f8d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f8e0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1f8f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1f900 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1f910 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1f920 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1f930 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1f940 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1f950 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f960 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f970 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f980 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1f990 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1f9a0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1f9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1f9c0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1f9d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f9e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1f9f0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1fa00 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1fa10 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1fa20 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1fa30 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1fa40 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1fa50 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1fa60 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1fa70 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1fa80 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1fa90 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1faa0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1fab0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1fac0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1fad0 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1fae0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1faf0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1fb00 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1fb10 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1fb20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
1fb30 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
1fb40 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
1fb50 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
1fb60 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
1fb70 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
1fb80 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
1fb90 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
1fba0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
1fbb0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
1fbc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1fbd0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1fbe0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1fbf0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1fc00 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1fc10 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1fc20 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1fc30 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1fc40 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1fc50 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1fc60 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1fc70 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1fc80 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1fc90 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1fca0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1fcb0 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1fcc0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1fcd0 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1fce0 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1fcf0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1fd00 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1fd10 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1fd20 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1fd30 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1fd40 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1fd50 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1fd60 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1fd70 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1fd80 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1fd90 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fda0 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1fdb0 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1fdc0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1fdd0 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1fde0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1fdf0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1fe00 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1fe10 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1fe20 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1fe30 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1fe40 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1fe50 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1fe60 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1fe70 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1fe80 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1fe90 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1fea0 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1feb0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1fec0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1fed0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1fee0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1fef0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1ff00 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1ff10 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1ff20 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1ff30 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1ff40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ff50 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1ff60 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1ff70 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1ff80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1ff90 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1ffa0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1ffb0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1ffc0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1ffd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1ffe0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1fff0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
20000 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
20010 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
20020 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
20030 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
20040 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
20050 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
20060 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
20070 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
20080 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
20090 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
200a0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
200b0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
200c0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
200d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
200e0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
200f0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
20100 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
20110 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
20120 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
20130 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
20140 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
20150 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
20160 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
20170 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
20180 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
20190 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
201a0 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
201b0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
201c0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
201d0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
201e0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
201f0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
20200 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
20210 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
20220 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
20230 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
20240 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
20250 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
20260 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
20270 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
20280 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
20290 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
202a0 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
202b0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
202c0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
202d0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
202e0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
202f0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
20300 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
20310 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
20320 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
20330 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
20340 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
20350 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
20360 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
20370 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
20380 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
20390 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
203a0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
203b0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
203c0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
203d0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
203e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
203f0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
20400 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
20410 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
20420 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
20430 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
20440 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20450 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
20460 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
20470 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
20480 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
20490 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
204a0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
204b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
204c0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
204d0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
204e0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
204f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20500 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
20510 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
20520 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
20530 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
20540 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
20550 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
20560 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
20570 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
20580 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
20590 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
205a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
205b0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
205c0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
205d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
205e0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
205f0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
20600 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
20610 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
20620 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
20630 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20640 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
20650 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
20660 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
20670 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
20680 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
20690 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
206a0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
206b0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
206c0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
206d0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
206e0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
206f0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
20700 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
20710 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
20720 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
20730 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
20740 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20750 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
20760 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
20770 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
20780 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
20790 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
207a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
207b0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
207c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
207d0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
207e0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
207f0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
20800 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
20810 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
20820 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
20830 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
20840 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
20850 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
20860 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
20870 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
20880 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
20890 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
208a0 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
208b0 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
208c0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
208d0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
208e0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
208f0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
20900 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
20910 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
20920 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20930 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
20940 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
20950 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
20960 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
20970 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
20980 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
20990 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
209a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
209b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
209c0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
209d0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
209e0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
209f0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
20a00 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
20a10 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
20a20 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
20a30 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
20a40 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
20a50 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
20a60 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
20a70 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
20a80 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
20a90 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
20aa0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
20ab0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
20ac0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
20ad0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
20ae0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
20af0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
20b00 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
20b10 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
20b20 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
20b30 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
20b40 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
20b50 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
20b60 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
20b70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
20b80 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20b90 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20ba0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
20bb0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20bc0 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
20bd0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
20be0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
20bf0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20c00 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
20c10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20c20 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20c30 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
20c40 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
20c50 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
20c60 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
20c70 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
20c80 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
20c90 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20ca0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
20cb0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20cc0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20cd0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
20ce0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
20cf0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
20d00 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
20d10 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
20d20 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
20d30 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20d40 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
20d50 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
20d60 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
20d70 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
20d80 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
20d90 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20da0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20db0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20dc0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
20dd0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
20de0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20df0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20e00 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
20e10 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
20e20 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
20e30 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
20e40 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
20e50 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
20e60 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
20e70 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
20e80 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
20e90 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
20ea0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
20eb0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
20ec0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
20ed0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
20ee0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
20ef0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
20f00 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
20f10 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
20f20 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
20f30 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
20f40 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
20f50 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
20f60 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
20f70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
20f80 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
20f90 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
20fa0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
20fb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20fc0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
20fd0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
20fe0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
20ff0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
21000 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
21010 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
21020 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
21030 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
21040 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
21050 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
21060 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
21070 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
21080 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21090 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
210a0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
210b0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
210c0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
210d0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
210e0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
210f0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
21100 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21110 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
21120 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21130 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
21140 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
21150 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
21160 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
21170 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
21180 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
21190 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
211a0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
211b0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
211c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
211d0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
211e0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
211f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21200 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
21210 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
21220 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21230 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
21240 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
21250 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
21260 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
21270 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
21280 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
21290 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
212a0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
212b0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
212c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
212d0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
212e0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
212f0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
21300 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
21310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
21320 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
21330 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
21340 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
21350 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
21360 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
21370 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
21380 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
21390 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
213a0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
213b0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
213c0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
213d0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
213e0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
213f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
21400 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
21410 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
21420 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
21430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21440 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
21450 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
21460 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
21470 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
21480 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
21490 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
214a0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
214b0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
214c0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
214d0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
214e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
214f0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
21500 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
21510 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
21520 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
21530 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
21540 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
21550 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
21560 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
21570 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
21580 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
21590 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
215a0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
215b0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
215c0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
215d0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
215e0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
215f0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
21600 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
21610 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
21620 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21630 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
21640 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
21650 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
21660 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
21670 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
21680 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
21690 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
216a0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
216b0 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
216c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
216d0 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
216e0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
216f0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
21700 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
21710 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
21720 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
21730 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
21740 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21750 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
21760 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
21770 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
21780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21790 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
217a0 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
217b0 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
217c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
217d0 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
217e0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
217f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
21800 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
21810 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
21820 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
21830 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
21840 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
21850 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
21860 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21870 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
21880 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
21890 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
218a0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
218b0 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
218c0 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
218d0 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
218e0 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
218f0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
21900 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
21910 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
21920 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
21930 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
21940 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
21950 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
21960 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
21970 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
21980 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
21990 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
219a0 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
219b0 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
219c0 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
219d0 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
219e0 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
219f0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
21a00 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
21a10 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
21a20 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
21a30 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
21a40 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
21a50 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
21a60 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
21a70 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
21a80 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
21a90 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
21aa0 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
21ab0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
21ac0 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
21ad0 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
21ae0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
21af0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
21b00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21b10 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
21b20 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
21b30 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
21b40 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
21b50 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
21b60 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
21b70 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
21b80 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
21b90 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
21ba0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
21bb0 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
21bc0 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
21bd0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
21be0 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
21bf0 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
21c00 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
21c10 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
21c20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
21c30 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
21c40 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
21c50 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21c60 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
21c70 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
21c80 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
21c90 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
21ca0 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
21cb0 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
21cc0 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
21cd0 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
21ce0 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
21cf0 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
21d00 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
21d10 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
21d20 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
21d30 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
21d40 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
21d50 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
21d60 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
21d70 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
21d80 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
21d90 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
21da0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
21db0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
21dc0 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
21dd0 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
21de0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
21df0 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
21e00 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
21e10 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
21e20 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
21e30 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
21e40 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
21e50 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
21e60 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
21e70 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
21e80 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
21e90 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
21ea0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
21eb0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
21ec0 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
21ed0 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
21ee0 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
21ef0 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
21f00 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
21f10 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
21f20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21f30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21f40 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
21f50 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
21f60 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
21f70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
21f80 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
21f90 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
21fa0 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
21fb0 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
21fc0 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
21fd0 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
21fe0 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
21ff0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22000 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22010 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22020 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22030 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
22040 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
22050 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
22060 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
22070 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
22080 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
22090 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
220a0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
220b0 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
220c0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
220d0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
220e0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
220f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
22100 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
22110 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
22120 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
22130 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
22140 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
22150 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
22160 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
22170 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
22180 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
22190 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
221a0 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
221b0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
221c0 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
221d0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
221e0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
221f0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
22200 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
22210 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
22220 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
22230 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
22240 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
22250 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
22260 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
22270 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
22280 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
22290 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
222a0 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
222b0 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
222c0 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
222d0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
222e0 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
222f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
22300 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22310 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22320 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
22330 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
22340 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22350 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
22360 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
22370 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
22380 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
22390 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
223a0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
223b0 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
223c0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
223d0 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
223e0 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
223f0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
22400 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22410 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
22420 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
22430 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
22440 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
22450 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
22460 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
22470 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
22480 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
22490 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
224a0 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
224b0 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
224c0 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
224d0 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
224e0 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
224f0 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
22500 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
22510 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
22520 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22530 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
22540 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22550 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
22560 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
22570 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
22580 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
22590 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
225a0 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
225b0 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
225c0 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
225d0 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
225e0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
225f0 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
22600 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
22610 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
22620 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
22630 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
22640 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
22650 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
22660 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
22670 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
22680 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
22690 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
226a0 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
226b0 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
226c0 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
226d0 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
226e0 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
226f0 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
22700 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
22710 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
22720 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
22730 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
22740 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
22750 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
22760 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
22770 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
22780 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
22790 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
227a0 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
227b0 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
227c0 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
227d0 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
227e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
227f0 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
22800 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
22810 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
22820 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
22830 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
22840 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
22850 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
22860 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
22870 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
22880 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
22890 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
228a0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
228b0 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
228c0 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
228d0 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
228e0 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
228f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22900 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
22910 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
22920 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
22930 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
22940 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
22950 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
22960 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
22970 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
22980 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
22990 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
229a0 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
229b0 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
229c0 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
229d0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
229e0 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
229f0 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
22a00 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
22a10 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
22a20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
22a30 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
22a40 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
22a50 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
22a60 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22a70 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
22a80 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
22a90 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22aa0 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
22ab0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
22ac0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
22ad0 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
22ae0 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
22af0 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
22b00 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
22b10 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
22b20 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22b30 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
22b40 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
22b50 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
22b60 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
22b70 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
22b80 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
22b90 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
22ba0 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
22bb0 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
22bc0 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
22bd0 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
22be0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
22bf0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
22c00 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
22c10 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
22c20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22c30 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
22c40 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
22c50 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
22c60 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
22c70 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
22c80 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
22c90 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
22ca0 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
22cb0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
22cc0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22cd0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
22ce0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
22cf0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
22d00 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
22d10 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
22d20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
22d30 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
22d40 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
22d50 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
22d60 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
22d70 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
22d80 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
22d90 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
22da0 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
22db0 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
22dc0 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
22dd0 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
22de0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
22df0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
22e00 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
22e10 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
22e20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
22e30 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
22e40 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
22e50 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
22e60 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
22e70 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
22e80 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
22e90 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
22ea0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
22eb0 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
22ec0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22ed0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
22ee0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
22ef0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22f00 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
22f10 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
22f20 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
22f30 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
22f40 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
22f50 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
22f60 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
22f70 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
22f80 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
22f90 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
22fa0 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
22fb0 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
22fc0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
22fd0 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
22fe0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
22ff0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
23000 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
23010 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
23020 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
23030 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
23040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
23050 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
23060 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
23070 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
23080 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
23090 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
230a0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
230b0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
230c0 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
230d0 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
230e0 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
230f0 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
23100 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
23110 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
23120 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
23130 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
23140 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
23150 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
23160 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
23170 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
23180 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
23190 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
231a0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
231b0 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
231c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
231d0 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
231e0 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
231f0 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
23200 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
23210 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
23220 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
23230 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
23240 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
23250 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
23260 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
23270 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
23280 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
23290 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
232a0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
232b0 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
232c0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
232d0 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
232e0 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
232f0 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
23300 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
23310 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
23320 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
23330 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
23340 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
23350 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
23360 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
23370 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23380 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
23390 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
233a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
233b0 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
233c0 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
233d0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
233e0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
233f0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
23400 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
23410 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
23420 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
23430 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
23440 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
23450 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
23460 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
23470 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
23480 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
23490 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
234a0 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
234b0 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
234c0 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
234d0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
234e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
234f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23500 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
23510 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
23520 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
23530 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
23540 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
23550 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
23560 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
23570 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
23580 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
23590 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
235a0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
235b0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
235c0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
235d0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
235e0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
235f0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23600 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
23610 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
23620 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
23630 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
23640 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
23650 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
23660 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
23670 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
23680 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
23690 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
236a0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
236b0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
236c0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
236d0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
236e0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
236f0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23700 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23710 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
23720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23730 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
23740 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
23750 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
23760 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
23770 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
23780 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
23790 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
237a0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
237b0 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
237c0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
237d0 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
237e0 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
237f0 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
23800 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
23810 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
23820 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
23830 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
23840 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
23850 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
23860 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
23870 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
23880 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
23890 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
238a0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
238b0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
238c0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
238d0 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
238e0 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
238f0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
23900 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
23910 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
23920 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
23930 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
23940 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
23950 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
23960 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
23970 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
23980 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
23990 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
239a0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
239b0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
239c0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
239d0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
239e0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
239f0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
23a00 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
23a10 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
23a20 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
23a30 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23a40 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
23a50 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
23a60 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23a70 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
23a80 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
23a90 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
23aa0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
23ab0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
23ac0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
23ad0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
23ae0 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
23af0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
23b00 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
23b10 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
23b20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
23b30 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
23b40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
23b50 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23b60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
23b70 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
23b80 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
23b90 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
23ba0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
23bb0 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
23bc0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
23bd0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
23be0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
23bf0 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
23c00 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
23c10 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23c20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23c30 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
23c40 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
23c50 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
23c60 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
23c70 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
23c80 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
23c90 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
23ca0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
23cb0 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
23cc0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
23cd0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
23ce0 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
23cf0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
23d00 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
23d10 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
23d20 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
23d30 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23d40 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
23d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23d60 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
23d70 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
23d80 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
23d90 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
23da0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
23db0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
23dc0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
23dd0 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
23de0 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
23df0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
23e00 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
23e10 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
23e20 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
23e30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
23e40 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
23e50 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
23e60 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23e70 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23e80 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
23e90 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23ea0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
23eb0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
23ec0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
23ed0 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
23ee0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
23ef0 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
23f00 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
23f10 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
23f20 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
23f30 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
23f40 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
23f50 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
23f60 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
23f70 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
23f80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23f90 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23fa0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
23fb0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
23fc0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
23fd0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
23fe0 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
23ff0 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
24000 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
24010 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
24020 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
24030 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
24040 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
24050 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
24060 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
24070 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
24080 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
24090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
240a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
240b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
240c0 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
240d0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
240e0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
240f0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
24100 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
24110 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
24120 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
24130 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
24140 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
24150 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
24160 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
24170 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
24180 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
24190 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
241a0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
241b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
241c0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
241d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
241e0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
241f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
24200 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
24210 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
24220 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
24230 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
24240 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
24250 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
24260 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
24270 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
24280 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
24290 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
242a0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
242b0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
242c0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
242d0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
242e0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
242f0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
24300 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
24310 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
24320 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
24330 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
24340 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
24350 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
24360 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
24370 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
24380 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
24390 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
243a0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
243b0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
243c0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
243d0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
243e0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
243f0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
24400 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
24410 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
24420 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
24430 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24440 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
24450 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
24460 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
24470 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
24480 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
24490 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
244a0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
244b0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
244c0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
244d0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
244e0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
244f0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
24500 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
24510 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
24520 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
24530 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
24540 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
24550 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
24560 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
24570 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
24580 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
24590 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
245a0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
245b0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
245c0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
245d0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
245e0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
245f0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
24600 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
24610 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
24620 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
24630 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
24640 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
24650 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
24660 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
24670 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
24680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24690 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
246a0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
246b0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
246c0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
246d0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
246e0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
246f0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
24700 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
24710 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
24720 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
24730 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
24740 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
24750 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
24760 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
24770 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
24780 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
24790 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
247a0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
247b0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
247c0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
247d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
247e0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
247f0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
24800 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
24810 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
24820 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
24830 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
24840 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
24850 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
24860 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
24870 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
24880 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
24890 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
248a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
248b0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
248c0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
248d0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
248e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
248f0 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
24900 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
24910 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
24920 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
24930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
24940 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
24950 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
24960 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
24970 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
24980 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
24990 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
249a0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
249b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
249c0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
249d0 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
249e0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
249f0 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
24a00 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
24a10 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
24a20 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
24a30 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
24a40 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
24a50 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
24a60 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
24a70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24a80 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
24a90 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
24aa0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
24ab0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
24ac0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
24ad0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
24ae0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
24af0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
24b00 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
24b10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
24b20 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
24b30 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
24b40 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
24b50 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
24b60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
24b70 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
24b80 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
24b90 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
24ba0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
24bb0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
24bc0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
24bd0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
24be0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
24bf0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
24c00 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
24c10 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
24c20 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
24c30 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
24c40 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
24c50 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
24c60 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
24c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24c80 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
24c90 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
24ca0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
24cb0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
24cc0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
24cd0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
24ce0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
24cf0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
24d00 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
24d10 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
24d20 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
24d30 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
24d40 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
24d50 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
24d60 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
24d70 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
24d80 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
24d90 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
24da0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
24db0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
24dc0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
24dd0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
24de0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
24df0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
24e00 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
24e10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
24e20 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
24e30 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
24e40 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
24e50 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
24e60 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
24e70 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
24e80 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
24e90 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
24ea0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
24eb0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
24ec0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
24ed0 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
24ee0 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
24ef0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
24f00 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
24f10 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
24f20 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
24f30 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
24f40 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
24f50 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
24f60 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
24f70 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
24f80 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
24f90 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
24fa0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
24fb0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
24fc0 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
24fd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
24fe0 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
24ff0 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
25000 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
25010 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25020 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
25030 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
25040 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
25050 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
25060 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
25070 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
25080 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
25090 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
250a0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
250b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
250c0 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
250d0 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
250e0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
250f0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
25100 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
25110 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
25120 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
25130 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
25140 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
25150 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
25160 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
25170 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
25180 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
25190 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
251a0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
251b0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
251c0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
251d0 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
251e0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
251f0 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
25200 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
25210 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
25220 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
25230 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
25240 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
25250 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
25260 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
25270 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
25280 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
25290 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
252a0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
252b0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
252c0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
252d0 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
252e0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
252f0 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
25300 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
25310 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
25320 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
25330 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
25340 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
25350 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
25360 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
25370 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
25380 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
25390 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
253a0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
253b0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
253c0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
253d0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
253e0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
253f0 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
25400 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
25410 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
25420 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
25430 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
25440 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
25450 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
25460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25470 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
25480 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
25490 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
254a0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
254b0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
254c0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
254d0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
254e0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
254f0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
25500 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
25510 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
25520 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
25530 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
25540 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
25550 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
25560 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
25570 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
25580 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
25590 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
255a0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
255b0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
255c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
255d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
255e0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
255f0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
25600 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25610 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
25620 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
25630 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
25640 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
25650 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25660 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
25670 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25680 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
25690 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
256a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
256b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
256c0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
256d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
256e0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
256f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25700 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
25710 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25720 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
25730 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
25740 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
25750 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
25760 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
25770 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
25780 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
25790 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
257a0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
257b0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
257c0 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
257d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
257e0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
257f0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25800 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
25810 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25820 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
25830 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
25840 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
25850 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25860 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
25870 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
25880 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25890 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
258a0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
258b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
258c0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
258d0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
258e0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
258f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25900 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
25910 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25920 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
25930 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25940 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
25950 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
25960 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
25970 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
25980 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
25990 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
259a0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
259b0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
259c0 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
259d0 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
259e0 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
259f0 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
25a00 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
25a10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25a20 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25a30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25a40 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
25a50 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
25a60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25a70 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
25a80 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
25a90 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25aa0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
25ab0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
25ac0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
25ad0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25ae0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25af0 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
25b00 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
25b10 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
25b20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
25b30 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
25b40 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
25b50 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
25b60 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
25b70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25b80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
25b90 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
25ba0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
25bb0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
25bc0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
25bd0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25be0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25bf0 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
25c00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
25c10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
25c20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25c30 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
25c40 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
25c50 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
25c60 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
25c70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25c80 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
25c90 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25ca0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
25cb0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
25cc0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
25cd0 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
25ce0 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
25cf0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25d00 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
25d10 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e  THREADS]] ^(<dt>
25d20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
25d30 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e  KER_THREADS</dt>
25d40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25d50 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75  mum number of au
25d60 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74  xiliary worker t
25d70 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69  hreads that a si
25d80 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65  ngle.** [prepare
25d90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79  d statement] may
25da0 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a   start.</dd>)^.*
25db0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
25dc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25dd0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
25de0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
25df0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25e00 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
25e10 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
25e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25e30 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
25e40 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
25e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25e60 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
25e70 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
25e80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25e90 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
25ea0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
25eb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25ec0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
25ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
25ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25ef0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
25f00 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
25f10 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
25f20 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
25f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25f40 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
25f50 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25f60 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
25f70 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
25f80 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
25f90 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
25fa0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
25fb0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
25fc0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
25fd0 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
25fe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
25ff0 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20  R_THREADS       
26000 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41      11../*.** CA
26010 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
26020 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
26030 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
26040 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
26050 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
26060 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
26070 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
26080 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
26090 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
260a0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
260b0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
260c0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
260d0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
260e0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
260f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26100 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
26110 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
26120 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
26130 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
26140 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
26150 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
26160 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
26170 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
26180 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
26190 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
261a0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
261b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
261c0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
261d0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
261e0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
261f0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
26200 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
26210 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
26220 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
26230 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
26240 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
26250 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
26260 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
26280 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
26290 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
262a0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
262b0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
262c0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
262d0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
262e0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
262f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26300 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
26310 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
26320 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
26330 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
26340 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
26350 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
26360 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
26370 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
26380 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
26390 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
263a0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
263b0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
263c0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
263d0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
263e0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
263f0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
26400 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
26410 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
26420 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
26430 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
26440 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
26450 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
26460 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
26470 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
26480 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
26490 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
264a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
264b0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
264c0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
264d0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
264e0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
264f0 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
26500 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
26510 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
26520 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
26530 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
26540 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
26550 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
26560 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
26570 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
26580 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
26590 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
265a0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
265b0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
265c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
265d0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
265e0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
265f0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
26600 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
26610 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
26620 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
26630 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
26640 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
26650 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
26660 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
26670 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
26680 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
26690 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
266a0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
266b0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
266c0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
266d0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
266e0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
266f0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
26700 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
26710 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
26720 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
26730 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
26740 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
26750 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
26760 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
26770 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
26780 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
26790 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
267a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
267b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
267c0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
267d0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
267e0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
267f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
26800 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
26810 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
26820 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
26830 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
26840 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
26850 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
26860 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
26870 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26880 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
26890 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
268a0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
268b0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
268c0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
268d0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
268e0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
268f0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
26900 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
26910 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
26920 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
26930 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
26940 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
26950 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
26960 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26970 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
26980 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
26990 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
269a0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
269b0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
269c0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
269d0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
269e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
269f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
26a00 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
26a10 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
26a20 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
26a30 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26a40 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
26a50 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
26a60 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
26a70 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
26a80 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
26a90 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
26aa0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
26ab0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
26ac0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
26ad0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
26ae0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
26af0 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
26b00 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
26b10 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
26b20 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
26b30 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
26b40 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
26b50 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
26b60 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
26b70 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
26b80 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
26b90 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
26ba0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
26bb0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
26bc0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
26bd0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
26be0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
26bf0 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
26c00 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
26c10 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
26c20 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
26c30 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
26c40 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
26c50 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
26c60 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
26c70 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
26c80 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
26c90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26ca0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
26cb0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
26cc0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
26cd0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
26ce0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
26cf0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
26d00 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
26d10 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
26d20 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
26d30 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
26d40 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
26d50 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
26d60 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
26d70 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
26d80 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
26d90 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
26da0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
26db0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
26dc0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
26dd0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
26de0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
26df0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
26e00 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
26e10 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
26e20 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
26e30 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
26e40 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
26e50 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
26e60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
26e70 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
26e80 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
26e90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
26ea0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
26eb0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
26ec0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
26ed0 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
26ee0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
26ef0 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
26f00 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
26f10 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
26f20 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
26f30 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
26f40 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
26f50 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
26f60 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
26f70 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
26f80 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
26f90 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
26fa0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
26fb0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
26fc0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
26fd0 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
26fe0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
26ff0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
27000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
27010 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27020 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27030 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27040 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27050 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27060 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
27070 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27080 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27090 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
270a0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
270b0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
270c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
270d0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
270e0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
270f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27100 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27110 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27120 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27130 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
27140 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27150 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
27160 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
27170 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
27180 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
27190 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
271a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
271b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
271c0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
271d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
271e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
271f0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27200 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27210 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27220 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27230 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27240 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
27250 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27260 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
27270 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
27280 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
27290 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
272a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
272b0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
272c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
272d0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
272e0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
272f0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
27300 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
27310 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
27320 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27330 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
27340 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
27350 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27360 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
27370 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
27380 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
27390 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
273a0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
273b0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
273c0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
273d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
273e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
273f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
27400 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27410 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27420 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
27430 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
27440 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
27450 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
27460 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
27470 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
27480 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
27490 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
274a0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
274b0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
274c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
274d0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
274e0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
274f0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
27500 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
27510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27520 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
27530 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
27540 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
27550 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
27560 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
27570 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
27580 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
27590 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
275a0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
275b0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
275c0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
275d0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
275e0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
275f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27600 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27610 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
27620 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27630 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
27640 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
27660 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
27670 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
27680 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
27690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
276a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
276b0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
276c0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
276d0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
276e0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
276f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27700 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
27710 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
27720 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27730 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27740 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
27750 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
27760 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27770 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
27780 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
27790 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
277a0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
277b0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
277c0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
277d0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
277e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
277f0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
27800 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
27810 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
27820 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
27830 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
27840 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
27850 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
27860 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
27870 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
27880 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
27890 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
278a0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
278b0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
278c0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
278d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
278e0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
278f0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
27900 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
27910 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27920 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
27930 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
27940 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
27950 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
27960 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
27970 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
27980 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
27990 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
279a0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
279b0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
279c0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
279d0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
279e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
279f0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
27a00 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
27a10 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
27a20 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
27a30 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
27a40 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
27a50 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
27a60 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
27a70 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
27a80 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
27a90 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
27aa0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
27ab0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
27ac0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
27ad0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
27ae0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
27af0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
27b00 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
27b10 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
27b20 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
27b30 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
27b40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
27b50 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
27b60 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
27b70 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27b80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27b90 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
27ba0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
27bb0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
27bc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27bd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27be0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
27bf0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27c00 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
27c10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27c20 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
27c30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27c40 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
27c50 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
27c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27c70 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
27c80 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
27c90 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
27ca0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
27cb0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
27cc0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
27cd0 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
27ce0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
27cf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
27d00 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
27d10 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
27d20 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
27d30 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
27d40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
27d50 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
27d60 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
27d70 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
27d80 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
27d90 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
27da0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
27db0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27dc0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
27dd0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
27de0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
27df0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
27e00 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
27e10 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
27e20 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
27e30 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
27e40 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
27e50 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
27e60 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
27e70 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
27e80 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
27e90 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
27ea0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
27eb0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
27ec0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
27ed0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
27ee0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
27ef0 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
27f00 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
27f10 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
27f20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
27f30 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
27f40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
27f50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27f60 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
27f70 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
27f80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
27f90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27fa0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
27fb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27fc0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
27fd0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
27fe0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
27ff0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
28000 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
28010 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
28020 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
28030 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
28040 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
28050 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
28060 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
28070 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
28080 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28090 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
280a0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
280b0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
280c0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
280d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
280e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
280f0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
28100 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
28110 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
28120 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
28130 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
28140 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28150 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
28160 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
28170 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
28180 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
28190 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
281a0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
281b0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
281c0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
281d0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
281e0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
281f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
28200 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
28210 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28220 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
28230 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
28240 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
28250 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
28260 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
28270 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
28280 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
28290 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
282a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
282b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
282c0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
282d0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
282e0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
282f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28300 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
28310 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
28320 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
28330 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
28340 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
28350 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
28360 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
28370 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
28380 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
28390 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
283a0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
283b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
283c0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
283d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
283e0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
283f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
28400 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
28410 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28420 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28430 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28440 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
28450 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
28460 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
28470 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
28480 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
28490 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
284a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
284b0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
284c0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
284d0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
284e0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
284f0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28500 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28510 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
28520 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
28530 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
28540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28550 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
28560 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
28570 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
28580 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
28590 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
285a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
285b0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
285c0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
285d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
285e0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
285f0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
28600 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
28610 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
28620 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
28630 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28640 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
28650 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
28660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
28670 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
28680 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
28690 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
286a0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
286b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
286c0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
286d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
286e0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
286f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28700 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
28710 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
28720 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
28730 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
28740 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
28750 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
28760 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
28770 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
28780 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
28790 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
287a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
287b0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
287c0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
287d0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
287e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
287f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
28800 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28810 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28820 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
28830 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28850 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
28860 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
28870 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
28880 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
28890 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
288a0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
288b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
288c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
288d0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
288e0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
288f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
28900 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
28910 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
28920 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
28930 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
28940 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
28950 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
28960 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
28970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
28980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28990 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
289a0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
289b0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
289c0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
289d0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
289e0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
289f0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
28a00 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
28a10 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
28a20 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
28a30 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
28a40 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
28a50 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
28a60 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
28a70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28a80 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
28a90 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
28aa0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
28ab0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
28ac0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
28ad0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
28ae0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
28af0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
28b00 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
28b10 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
28b20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
28b30 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
28b40 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
28b50 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
28b60 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
28b70 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
28b80 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
28b90 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
28ba0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
28bb0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
28bc0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
28bd0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
28be0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
28bf0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
28c00 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
28c10 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
28c20 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
28c30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28c40 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
28c50 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
28c60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
28c70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28c80 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
28c90 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
28ca0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
28cb0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
28cc0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
28cd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
28ce0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
28cf0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
28d00 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
28d10 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
28d20 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
28d30 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
28d40 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
28d50 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
28d60 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
28d70 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
28d80 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
28d90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
28da0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
28db0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
28dc0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
28dd0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
28de0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
28df0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
28e00 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
28e10 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
28e20 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
28e30 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
28e40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
28e50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28e60 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
28e70 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
28e80 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
28e90 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
28ea0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
28eb0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
28ec0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
28ed0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
28ee0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
28ef0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
28f00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
28f10 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
28f20 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
28f30 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
28f40 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
28f50 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
28f60 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
28f70 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
28f80 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
28f90 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
28fa0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
28fb0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
28fc0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
28fd0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
28fe0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
28ff0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
29000 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
29010 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
29020 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
29030 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
29040 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
29050 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
29060 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
29070 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
29080 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
29090 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
290a0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
290b0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
290c0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
290d0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
290e0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
290f0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
29100 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
29110 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
29120 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
29130 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29140 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
29150 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29160 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
29170 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
29180 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
29190 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
291a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
291b0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
291c0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
291d0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
291e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
291f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29200 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
29210 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
29220 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
29230 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
29240 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
29250 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
29260 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
29270 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
29280 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29290 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
292a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
292b0 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
292c0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
292d0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
292e0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
292f0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
29300 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
29310 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
29320 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
29330 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
29340 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
29350 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
29360 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
29370 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
29380 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29390 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
293a0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
293b0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
293c0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
293d0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
293e0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
293f0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
29400 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
29410 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
29420 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
29430 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
29440 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
29450 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
29460 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
29470 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
29480 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
29490 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
294a0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
294b0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
294c0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
294d0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
294e0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
294f0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
29500 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
29510 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
29520 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
29530 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
29540 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
29550 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
29560 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
29570 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
29580 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
29590 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
295a0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
295b0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
295c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
295d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
295e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
295f0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
29600 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
29610 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
29620 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
29630 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
29640 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
29650 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
29660 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29670 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
29680 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
29690 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
296a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
296b0 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
296c0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
296d0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
296e0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
296f0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
29700 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
29710 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
29720 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
29730 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
29740 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
29750 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
29760 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
29770 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
29780 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
29790 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
297a0 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
297b0 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
297c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
297d0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
297e0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
297f0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
29800 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
29810 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
29820 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
29830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29840 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
29850 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
29860 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
29870 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
29880 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
29890 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
298a0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
298b0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
298c0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
298d0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
298e0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
298f0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
29900 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
29910 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
29920 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
29930 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
29940 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
29950 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
29960 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
29970 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
29980 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
29990 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
299a0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
299b0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
299c0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
299d0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
299e0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
299f0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
29a00 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
29a10 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
29a20 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
29a30 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
29a40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29a50 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
29a60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
29a70 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
29a80 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
29a90 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
29aa0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
29ab0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29ac0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
29ad0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
29ae0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
29af0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
29b00 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
29b10 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
29b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29b30 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
29b40 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
29b50 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
29b60 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
29b70 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
29b80 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
29b90 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
29ba0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
29bb0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
29bc0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
29bd0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
29be0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
29bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29c00 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
29c10 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
29c20 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
29c30 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
29c40 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
29c50 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
29c60 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
29c70 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
29c80 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
29c90 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
29ca0 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
29cb0 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
29cc0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
29cd0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
29ce0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
29cf0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
29d00 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
29d10 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
29d20 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
29d30 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
29d40 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
29d50 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
29d60 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
29d70 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
29d80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29d90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29da0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
29db0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29dc0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
29dd0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
29de0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29df0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
29e00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29e10 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
29e20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
29e30 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
29e40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
29e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29e60 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
29e70 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
29e80 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
29e90 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
29ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
29eb0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
29ec0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
29ed0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
29ee0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
29ef0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29f00 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
29f10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
29f20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29f30 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
29f40 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
29f50 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
29f60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
29f70 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
29f80 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
29f90 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
29fa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
29fb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
29fc0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29fd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29fe0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
29ff0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2a000 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2a010 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2a020 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a030 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2a040 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2a050 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2a060 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2a070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a080 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2a090 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2a0a0 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
2a0b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2a0c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a0d0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2a0e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2a0f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2a100 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2a110 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2a120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a130 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2a140 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
2a150 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2a160 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2a170 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2a180 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2a190 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2a1a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a1b0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2a1c0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2a1d0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2a1e0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2a1f0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2a200 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2a210 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2a220 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2a230 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2a240 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2a250 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2a260 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2a270 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2a280 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2a290 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2a2a0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2a2b0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2a2c0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2a2d0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2a2e0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2a2f0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2a300 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2a310 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2a320 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2a330 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2a340 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2a350 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2a360 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2a370 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2a380 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2a390 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2a3a0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2a3b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a3c0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2a3d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a3e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a3f0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2a400 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a410 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2a420 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2a430 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2a440 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2a450 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
2a460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a470 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2a480 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a490 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2a4a0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2a4b0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2a4c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a4d0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2a4e0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2a4f0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2a500 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2a510 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2a520 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2a530 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2a540 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2a550 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2a560 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2a570 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2a580 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2a590 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2a5a0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2a5b0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2a5c0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2a5d0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2a5e0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2a5f0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2a600 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2a610 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2a620 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2a630 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2a640 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2a650 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2a660 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2a670 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2a680 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2a690 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2a6a0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2a6b0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2a6c0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2a6d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2a6e0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2a6f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2a700 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2a710 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2a720 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2a730 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2a740 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2a750 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2a760 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2a770 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2a780 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2a790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2a7a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2a7b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a7c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a7d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2a7e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a7f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a800 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2a810 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a820 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2a830 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2a840 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a850 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2a860 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2a870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a880 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2a890 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2a8a0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
2a8b0 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2a8c0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2a8d0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2a8e0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2a8f0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2a900 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2a910 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2a920 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2a930 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2a940 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2a950 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2a960 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2a970 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2a980 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2a990 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2a9a0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2a9b0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2a9c0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2a9d0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2a9e0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2a9f0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2aa00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2aa10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2aa20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2aa30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2aa40 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2aa50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2aa60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2aa70 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2aa80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2aa90 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2aaa0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2aab0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2aac0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2aad0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2aae0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2aaf0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2ab00 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2ab10 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2ab20 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
2ab30 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2ab40 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2ab50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ab60 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2ab70 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2ab80 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2ab90 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2aba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2abb0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2abc0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2abd0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2abe0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2abf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2ac00 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2ac10 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2ac20 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2ac30 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2ac40 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2ac50 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2ac60 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2ac70 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2ac80 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2ac90 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2aca0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2acb0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2acc0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2acd0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2ace0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2acf0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2ad00 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2ad10 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2ad20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ad30 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2ad40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ad50 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2ad60 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ad70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ad80 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2ad90 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2ada0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2adb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2adc0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2add0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2ade0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2adf0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2ae00 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ae10 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2ae20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2ae30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2ae40 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2ae50 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2ae60 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2ae70 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2ae80 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2ae90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2aea0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2aeb0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2aec0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2aed0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2aee0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2aef0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2af00 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2af10 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2af20 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2af30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2af40 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2af50 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2af60 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2af70 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2af80 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2af90 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2afa0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2afb0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2afc0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2afd0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2afe0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2aff0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2b000 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2b010 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2b020 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2b030 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2b040 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2b050 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2b060 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2b070 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2b080 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2b090 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2b0a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2b0b0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2b0c0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2b0d0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2b0e0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2b0f0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2b100 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2b110 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2b120 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2b130 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2b140 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2b150 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2b160 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2b170 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2b180 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2b190 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2b1a0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2b1b0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2b1c0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2b1d0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2b1e0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2b1f0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2b200 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2b210 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2b220 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2b230 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2b240 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2b250 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2b260 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
2b270 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b280 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b290 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
2b2a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2b2b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2b2c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b2d0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2b2e0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2b2f0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2b300 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
2b310 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2b320 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2b330 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2b340 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2b350 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2b360 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2b370 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2b380 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2b390 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2b3a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2b3b0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2b3c0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2b3d0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2b3e0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2b3f0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2b400 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2b410 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2b420 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2b430 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2b440 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2b450 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2b460 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2b470 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2b480 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2b490 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2b4a0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2b4b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b4c0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2b4d0 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2b4e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2b4f0 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2b500 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2b510 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2b520 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2b530 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2b540 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2b550 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2b560 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b570 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2b580 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2b590 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2b5a0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2b5b0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2b5c0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2b5d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2b5e0 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2b5f0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2b600 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2b610 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2b620 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2b630 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2b640 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2b650 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2b660 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2b670 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b680 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2b690 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2b6a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2b6b0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2b6c0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2b6d0 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2b6e0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2b6f0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2b700 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2b710 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2b720 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2b730 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2b740 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2b750 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2b760 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2b770 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2b780 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2b790 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2b7a0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2b7b0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2b7c0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2b7d0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2b7e0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2b7f0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2b800 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2b810 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2b820 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2b830 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2b840 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2b850 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2b860 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2b870 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2b880 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2b890 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2b8a0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2b8b0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2b8c0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2b8d0 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2b8e0 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2b8f0 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2b900 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2b910 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2b920 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2b930 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2b940 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2b950 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2b960 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2b970 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2b980 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2b990 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2b9a0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2b9b0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2b9c0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2b9d0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2b9e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2b9f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2ba00 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2ba10 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2ba20 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2ba30 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2ba40 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2ba50 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2ba60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2ba70 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2ba80 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2ba90 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2baa0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2bab0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2bac0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2bad0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2bae0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2baf0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2bb00 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2bb10 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2bb20 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2bb30 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2bb40 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2bb60 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2bb70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2bb80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2bb90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2bba0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2bbb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2bbc0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2bbd0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2bbe0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2bbf0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2bc00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bc10 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2bc20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2bc30 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2bc40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2bc50 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2bc60 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2bc70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2bc80 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2bc90 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2bca0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2bcb0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2bcc0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2bcd0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2bce0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2bcf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2bd00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bd10 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2bd20 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2bd30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2bd40 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2bd50 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2bd60 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2bd70 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2bd80 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2bd90 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2bda0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2bdb0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2bdc0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2bdd0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2bde0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2bdf0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2be00 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2be10 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2be20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2be30 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2be40 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2be50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2be60 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2be70 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2be80 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2be90 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2bea0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2beb0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2bec0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2bed0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2bee0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2bef0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2bf00 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2bf10 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2bf20 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2bf30 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2bf40 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2bf50 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2bf60 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2bf70 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2bf80 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2bf90 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2bfa0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2bfb0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2bfc0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2bfd0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2bfe0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2bff0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2c000 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2c010 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2c020 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2c030 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2c040 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2c050 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2c060 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2c070 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2c080 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2c090 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2c0a0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2c0b0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2c0c0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2c0d0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2c0e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2c0f0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2c100 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2c110 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2c120 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2c130 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
2c140 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2c150 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2c160 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c170 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2c180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2c190 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2c1a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2c1b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2c1c0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2c1d0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
2c1e0 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
2c1f0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
2c200 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
2c210 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
2c220 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c230 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2c240 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2c250 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
2c260 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2c270 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2c280 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
2c290 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
2c2a0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2c2b0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2c2c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2c2d0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
2c2e0 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
2c2f0 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
2c300 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
2c310 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
2c320 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
2c330 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
2c340 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
2c350 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
2c360 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
2c370 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
2c380 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c390 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2c3a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c3b0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
2c3c0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
2c3d0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
2c3e0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2c3f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c400 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
2c410 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
2c420 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2c430 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
2c440 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
2c450 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
2c460 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
2c470 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
2c480 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
2c490 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
2c4a0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
2c4b0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
2c4c0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
2c4d0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
2c4e0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
2c4f0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
2c500 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
2c510 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
2c520 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
2c530 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
2c540 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
2c550 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
2c560 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2c570 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
2c580 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
2c590 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
2c5a0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
2c5b0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
2c5c0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
2c5d0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
2c5e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
2c5f0 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
2c600 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
2c610 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2c620 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
2c630 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
2c640 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
2c650 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2c660 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
2c670 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
2c680 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
2c690 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
2c6a0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
2c6b0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
2c6c0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2c6d0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
2c6e0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
2c6f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
2c700 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
2c710 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2c720 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
2c730 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
2c740 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
2c750 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
2c760 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
2c770 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2c780 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2c790 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
2c7a0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
2c7b0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
2c7c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2c7d0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
2c7e0 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
2c7f0 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
2c800 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
2c810 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
2c820 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
2c830 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
2c840 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
2c850 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
2c860 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
2c870 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
2c880 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
2c890 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
2c8a0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
2c8b0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
2c8c0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
2c8d0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
2c8e0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2c8f0 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
2c900 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
2c910 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
2c920 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
2c930 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
2c940 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
2c950 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
2c960 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
2c970 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
2c980 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
2c990 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
2c9a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2c9b0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2c9c0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
2c9d0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
2c9e0 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
2c9f0 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
2ca00 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2ca10 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2ca20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2ca30 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
2ca40 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
2ca50 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
2ca60 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2ca70 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
2ca80 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
2ca90 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
2caa0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
2cab0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
2cac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cad0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
2cae0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2caf0 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
2cb00 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
2cb10 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2cb20 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2cb30 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2cb40 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2cb50 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
2cb60 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
2cb70 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
2cb80 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
2cb90 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
2cba0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
2cbb0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
2cbc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cbd0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
2cbe0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
2cbf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2cc00 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
2cc10 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
2cc20 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
2cc30 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
2cc40 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
2cc50 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
2cc60 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
2cc70 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
2cc80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2cc90 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
2cca0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
2ccb0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
2ccc0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
2ccd0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
2cce0 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
2ccf0 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
2cd00 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
2cd10 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
2cd20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
2cd30 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
2cd40 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
2cd50 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
2cd60 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
2cd70 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2cd80 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
2cd90 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
2cda0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
2cdb0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
2cdc0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
2cdd0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2cde0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
2cdf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ce00 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
2ce10 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
2ce20 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
2ce30 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
2ce40 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
2ce50 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
2ce60 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
2ce70 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
2ce80 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ce90 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
2cea0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
2ceb0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
2cec0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
2ced0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2cee0 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
2cef0 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
2cf00 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
2cf10 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
2cf20 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
2cf30 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
2cf40 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
2cf50 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
2cf60 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
2cf70 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
2cf80 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
2cf90 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2cfa0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
2cfb0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
2cfc0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
2cfd0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
2cfe0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
2cff0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
2d000 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2d010 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
2d020 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
2d030 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
2d040 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
2d050 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
2d060 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
2d070 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
2d080 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
2d090 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d0a0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
2d0b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2d0c0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2d0d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
2d0e0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
2d0f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
2d100 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2d110 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
2d120 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2d130 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
2d140 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
2d150 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
2d160 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
2d170 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
2d180 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2d190 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
2d1a0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
2d1b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
2d1c0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
2d1d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d1e0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2d1f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2d200 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
2d210 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
2d220 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2d230 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2d240 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
2d250 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
2d260 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2d270 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
2d280 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
2d290 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
2d2a0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
2d2b0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
2d2c0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2d2d0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
2d2e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2d2f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2d300 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2d310 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2d320 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2d330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d340 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d350 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d360 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2d370 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2d380 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2d390 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2d3a0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2d3b0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2d3c0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2d3d0 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2d3e0 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2d3f0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2d400 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2d410 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2d420 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2d430 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2d440 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2d450 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2d460 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2d470 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2d480 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2d490 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2d4a0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2d4b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2d4c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d4d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2d4e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d4f0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2d500 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2d510 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2d520 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d530 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2d540 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2d550 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2d560 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2d570 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2d580 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2d590 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2d5a0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2d5b0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2d5c0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2d5d0 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2d5e0 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2d5f0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2d600 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2d610 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2d620 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2d630 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2d640 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2d650 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2d660 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2d670 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2d680 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2d690 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d6a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d6b0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2d6c0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2d6d0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2d6e0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2d6f0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2d700 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2d710 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2d720 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2d730 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2d740 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2d750 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2d760 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2d770 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2d780 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2d790 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2d7a0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2d7b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2d7c0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2d7d0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2d7e0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2d7f0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2d800 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2d810 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2d820 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d830 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2d840 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2d850 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2d860 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2d870 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2d880 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2d890 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2d8a0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2d8b0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2d8c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2d8d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2d8e0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2d8f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2d900 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2d910 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2d920 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2d930 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2d940 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2d950 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2d960 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2d970 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2d980 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2d990 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2d9a0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2d9b0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2d9c0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2d9d0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2d9e0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2d9f0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2da00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2da10 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2da20 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2da30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2da40 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2da50 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2da60 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2da70 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2da80 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2da90 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2daa0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2dab0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2dac0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2dad0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dae0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2daf0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2db00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2db10 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2db20 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2db30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2db40 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2db50 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2db60 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2db70 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2db80 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2db90 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2dba0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2dbb0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2dbc0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2dbd0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2dbe0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2dbf0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2dc00 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2dc10 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2dc20 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2dc30 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2dc40 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2dc50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2dc60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2dc70 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2dc80 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2dc90 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2dca0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2dcb0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2dcc0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2dcd0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2dce0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2dcf0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2dd00 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2dd10 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2dd20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2dd30 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2dd40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2dd50 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2dd60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2dd70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2dd80 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2dd90 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2dda0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2ddb0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2ddc0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2ddd0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2dde0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2ddf0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2de00 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2de10 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2de20 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2de30 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2de40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2de50 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2de60 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2de70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2de80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2de90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2dea0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2deb0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2dec0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2ded0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2dee0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2def0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2df00 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2df10 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2df20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2df30 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2df40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2df50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2df60 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2df70 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2df80 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2df90 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2dfa0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2dfb0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2dfc0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2dfd0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2dfe0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2dff0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2e000 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2e010 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2e020 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2e030 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2e040 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2e050 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2e060 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2e070 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2e080 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2e090 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2e0a0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2e0b0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2e0c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2e0d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2e0e0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2e0f0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2e100 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2e110 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2e120 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2e130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2e140 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2e150 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2e160 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2e170 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2e180 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2e190 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2e1a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e1b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2e1c0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2e1d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2e1e0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2e1f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e200 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2e210 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2e220 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e230 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2e240 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2e250 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2e260 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e270 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2e280 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2e290 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2e2a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e2b0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2e2c0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2e2d0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2e2e0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2e2f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2e300 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2e310 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e320 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2e330 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e340 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2e350 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e360 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2e370 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2e380 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2e390 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2e3a0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2e3b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e3c0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2e3d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2e3e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e3f0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2e400 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e410 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2e420 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2e430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e440 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2e450 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2e460 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2e470 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2e480 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2e490 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e4a0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2e4b0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2e4c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e4d0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2e4e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2e4f0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2e500 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2e510 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2e520 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2e530 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e540 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2e550 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e560 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2e570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e580 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2e590 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2e5a0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2e5b0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2e5c0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2e5d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e5e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2e5f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2e600 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2e610 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2e620 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2e630 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2e640 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2e650 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2e660 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2e670 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2e680 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2e690 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2e6a0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2e6b0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2e6c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2e6d0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2e6e0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2e6f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2e700 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2e710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e720 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2e730 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2e740 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2e750 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2e760 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2e770 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2e780 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2e790 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2e7a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e7b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2e7c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2e7d0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2e7e0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2e7f0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2e800 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e810 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2e820 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e830 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2e840 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2e850 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2e860 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2e870 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2e880 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2e890 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2e8a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e8b0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2e8c0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2e8d0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2e8e0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2e8f0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2e900 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2e910 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2e920 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2e930 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2e940 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2e950 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2e960 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2e970 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2e980 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2e990 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2e9a0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2e9b0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2e9c0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2e9d0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2e9e0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2e9f0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2ea00 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2ea10 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2ea20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2ea30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2ea40 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2ea50 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2ea60 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2ea70 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2ea80 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2ea90 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2eaa0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2eab0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2eac0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2ead0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2eae0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2eaf0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2eb00 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2eb10 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2eb20 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2eb30 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2eb40 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2eb50 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2eb60 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2eb70 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2eb80 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2eb90 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2eba0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2ebb0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2ebc0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2ebd0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2ebe0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2ebf0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2ec00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
2ec10 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
2ec20 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2ec30 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2ec40 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2ec50 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2ec60 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2ec70 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2ec80 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2ec90 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2eca0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2ecb0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2ecc0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2ecd0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2ece0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2ecf0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2ed00 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2ed10 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2ed20 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2ed30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2ed40 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2ed50 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2ed60 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2ed70 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2ed80 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2ed90 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
2eda0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
2edb0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2edc0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2edd0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2ede0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2edf0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2ee00 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2ee10 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2ee20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2ee30 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2ee40 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2ee50 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2ee60 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2ee70 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
2ee80 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
2ee90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2eea0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2eeb0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2eec0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
2eed0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2eee0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2eef0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2ef00 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2ef10 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2ef20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2ef30 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2ef40 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2ef50 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2ef60 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2ef70 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2ef80 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2ef90 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2efa0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2efb0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2efc0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2efd0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2efe0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2eff0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2f000 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2f010 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2f020 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2f030 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2f040 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2f050 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2f060 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2f070 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2f080 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2f090 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2f0a0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2f0b0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2f0c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2f0d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f0e0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2f0f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f100 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2f110 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2f120 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2f130 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2f140 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2f150 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2f160 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2f170 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2f180 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2f190 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2f1a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2f1b0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2f1c0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2f1d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2f1e0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2f1f0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2f200 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2f210 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2f220 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2f230 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2f240 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2f250 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2f260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f270 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2f280 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f290 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2f2a0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2f2b0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2f2c0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2f2d0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2f2e0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2f2f0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2f300 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2f310 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f320 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2f330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f340 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2f350 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2f360 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2f370 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2f380 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2f390 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2f3a0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2f3b0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2f3c0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2f3d0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2f3e0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2f3f0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2f400 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2f410 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2f420 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2f430 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2f440 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2f450 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2f460 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2f470 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2f480 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2f490 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2f4a0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2f4b0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2f4c0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2f4d0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2f4e0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2f4f0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2f500 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2f510 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2f520 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2f530 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2f540 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2f550 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2f560 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2f570 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2f580 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2f590 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2f5a0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2f5b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f5c0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2f5d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f5e0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2f5f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f600 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2f610 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2f620 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2f630 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2f640 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f650 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2f660 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2f670 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2f680 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2f690 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2f6a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f6b0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2f6c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f6d0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2f6e0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2f6f0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2f700 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2f710 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2f720 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2f730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f740 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2f750 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2f760 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2f770 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2f780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f790 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2f7a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2f7b0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2f7c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f7d0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2f7e0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2f7f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2f800 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2f810 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2f820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f830 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2f840 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2f850 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2f860 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f870 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2f880 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2f890 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2f8a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2f8b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f8c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2f8d0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2f8e0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2f8f0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2f900 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2f910 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2f920 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2f930 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2f940 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2f950 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2f960 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
2f970 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2f980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f990 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2f9a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2f9b0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2f9c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2f9d0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2f9e0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2f9f0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2fa00 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2fa10 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2fa20 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2fa30 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2fa40 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2fa50 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2fa60 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2fa70 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2fa80 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2fa90 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2faa0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2fab0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2fac0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2fad0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2fae0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2faf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2fb00 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2fb10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2fb20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fb30 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2fb40 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2fb50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2fb60 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2fb70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2fb80 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
2fb90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2fba0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2fbb0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2fbc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2fbd0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2fbe0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2fbf0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2fc00 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2fc10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fc20 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2fc30 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2fc40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fc50 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2fc60 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2fc70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2fc80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2fc90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fca0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2fcb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2fcc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fcd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2fce0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2fcf0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2fd00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fd10 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2fd20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2fd30 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2fd40 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2fd50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fd60 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2fd70 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2fd80 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2fd90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2fda0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2fdb0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2fdc0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2fdd0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2fde0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2fdf0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2fe00 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2fe10 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2fe20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fe30 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2fe40 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2fe50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2fe60 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2fe70 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2fe80 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2fe90 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2fea0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2feb0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2fec0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2fed0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2fee0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fef0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2ff00 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2ff10 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2ff20 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2ff30 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2ff40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ff50 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2ff60 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2ff70 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2ff80 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2ff90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2ffa0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2ffb0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2ffc0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2ffd0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2ffe0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2fff0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
30000 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
30010 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
30020 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
30030 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
30040 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
30050 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
30060 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
30070 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
30080 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
30090 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
300a0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
300b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
300c0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
300d0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
300e0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
300f0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
30100 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
30110 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
30120 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
30130 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
30140 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
30150 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
30160 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
30170 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
30180 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
30190 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
301a0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
301b0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
301c0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
301d0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
301e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
301f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30210 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
30220 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
30230 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
30240 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
30250 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
30260 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
30270 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30280 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
30290 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
302a0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
302b0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
302c0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
302d0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
302e0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
302f0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
30300 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
30310 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
30320 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
30330 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
30340 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
30350 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
30360 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
30370 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
30380 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
30390 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
303a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
303b0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
303c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
303d0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
303e0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
303f0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
30400 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30410 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30420 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
30430 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
30440 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
30450 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
30460 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
30470 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
30480 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
30490 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
304a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
304b0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
304c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
304d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
304e0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
304f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
30500 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30510 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
30520 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30530 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
30540 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
30550 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
30560 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
30570 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
30580 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
30590 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
305a0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
305b0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
305c0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
305d0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
305e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
305f0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
30600 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30610 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
30620 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
30630 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
30640 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30650 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
30660 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
30670 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
30680 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
30690 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
306a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
306b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
306c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
306d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
306e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
306f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
30700 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
30710 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
30720 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
30730 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
30740 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
30750 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
30760 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
30770 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
30780 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
30790 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
307a0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
307b0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
307c0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
307d0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
307e0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
307f0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
30800 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
30810 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
30820 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
30830 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
30840 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
30850 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
30860 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
30870 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
30880 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
30890 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
308a0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
308b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
308c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
308d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
308e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
308f0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
30900 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
30910 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
30920 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
30930 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
30940 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
30950 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
30960 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
30970 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
30980 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
30990 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
309a0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
309b0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
309c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
309d0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
309e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
309f0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
30a00 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
30a10 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
30a20 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
30a30 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
30a40 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
30a50 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
30a60 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
30a70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
30a80 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
30a90 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
30aa0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
30ab0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
30ac0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
30ad0 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
30ae0 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
30af0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
30b00 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
30b10 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
30b20 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
30b30 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
30b40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
30b50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
30b60 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
30b70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
30b80 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
30b90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
30ba0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
30bb0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
30bc0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
30bd0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
30be0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
30bf0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
30c00 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
30c10 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
30c20 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
30c30 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
30c40 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
30c50 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
30c60 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
30c70 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
30c80 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
30c90 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
30ca0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
30cb0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
30cc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30cd0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
30ce0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
30cf0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
30d00 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
30d10 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
30d20 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
30d30 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
30d40 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
30d50 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
30d60 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
30d70 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
30d80 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
30d90 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
30da0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30db0 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
30dc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30dd0 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
30de0 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
30df0 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
30e00 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
30e10 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
30e20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30e30 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
30e40 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
30e50 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
30e60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
30e70 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
30e80 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
30e90 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
30ea0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
30eb0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
30ec0 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
30ed0 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
30ee0 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
30ef0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
30f00 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
30f10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
30f20 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
30f30 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
30f40 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
30f50 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
30f60 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
30f70 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
30f80 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
30f90 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
30fa0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
30fb0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
30fc0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
30fd0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
30fe0 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
30ff0 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
31000 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
31010 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
31020 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
31030 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
31040 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
31050 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
31060 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
31070 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
31080 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
31090 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
310a0 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
310b0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
310c0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
310d0 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
310e0 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
310f0 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
31100 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
31110 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
31120 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
31130 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
31140 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
31150 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
31160 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
31170 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
31180 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
31190 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
311a0 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
311b0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
311c0 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
311d0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
311e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
311f0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
31200 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
31210 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
31220 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
31230 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
31240 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
31250 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
31260 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
31270 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
31280 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
31290 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
312a0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
312b0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
312c0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
312d0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
312e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
312f0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
31300 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
31310 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
31320 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
31330 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
31340 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
31350 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
31360 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
31370 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
31380 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
31390 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
313a0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
313b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
313c0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
313d0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
313e0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
313f0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
31400 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
31410 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
31420 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
31430 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
31440 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
31450 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
31460 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
31470 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
31480 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
31490 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
314a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
314b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
314c0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
314d0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
314e0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
314f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
31500 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
31510 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
31520 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
31530 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
31540 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
31550 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
31560 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
31570 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
31580 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
31590 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
315a0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
315b0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
315c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
315d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
315e0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
315f0 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
31600 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
31610 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
31620 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
31630 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
31640 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
31650 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
31660 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
31670 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
31680 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
31690 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
316a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
316b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
316c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
316d0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
316e0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
316f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
31700 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
31710 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
31720 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
31730 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
31740 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
31750 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
31760 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
31770 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
31780 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
31790 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
317a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
317b0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
317c0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
317d0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
317e0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
317f0 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
31800 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31810 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
31820 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
31830 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
31840 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
31850 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
31860 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
31870 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
31880 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
31890 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
318a0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
318b0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
318c0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
318d0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
318e0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
318f0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
31900 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
31910 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
31920 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
31930 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
31940 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
31950 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
31960 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
31970 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
31980 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
31990 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
319a0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
319b0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
319c0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
319d0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
319e0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
319f0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
31a00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31a10 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
31a20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31a30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
31a40 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
31a50 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
31a60 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
31a70 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
31a80 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
31a90 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
31aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
31ab0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
31ac0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
31ad0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
31ae0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
31af0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31b00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
31b10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
31b20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
31b30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
31b40 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
31b50 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
31b60 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
31b70 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
31b80 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
31b90 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31ba0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31bb0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
31bc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31bd0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31be0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
31bf0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
31c00 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
31c10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31c20 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
31c30 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
31c40 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
31c50 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
31c60 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31c70 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
31c80 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
31c90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31ca0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
31cb0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
31cc0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
31cd0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31ce0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31cf0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
31d00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
31d10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
31d20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
31d30 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
31d40 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
31d50 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
31d60 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
31d70 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
31d80 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
31d90 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
31da0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31db0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31dc0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31dd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31de0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31df0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31e00 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
31e10 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
31e20 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
31e30 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
31e40 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
31e50 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
31e60 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
31e70 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
31e80 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
31e90 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
31ea0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
31eb0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
31ec0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
31ed0 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
31ee0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
31ef0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
31f00 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
31f10 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
31f20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
31f30 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
31f40 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
31f50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31f60 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
31f70 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
31f80 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
31f90 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
31fa0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
31fb0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
31fc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31fd0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
31fe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31ff0 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
32000 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32010 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
32020 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
32030 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
32040 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
32050 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
32060 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
32070 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
32080 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32090 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
320a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
320b0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
320c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
320d0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
320e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
320f0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
32100 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
32110 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
32120 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
32130 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
32140 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
32150 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
32160 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
32170 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
32180 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
32190 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
321a0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
321b0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
321c0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
321d0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
321e0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
321f0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
32200 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
32210 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
32220 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
32230 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
32240 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
32250 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
32260 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
32270 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
32280 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
32290 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
322a0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
322b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
322c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
322d0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
322e0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
322f0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32300 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
32310 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
32320 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32330 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
32340 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
32350 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
32360 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
32370 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32380 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
32390 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
323a0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
323b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
323c0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
323d0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
323e0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
323f0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
32400 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
32410 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
32420 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
32430 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
32440 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
32450 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
32460 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
32470 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
32480 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
32490 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
324a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
324b0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
324c0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
324d0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
324e0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
324f0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
32500 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
32510 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
32520 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
32530 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
32540 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
32550 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
32560 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
32570 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
32580 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
32590 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
325a0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
325b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
325c0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
325d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
325e0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
325f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
32600 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
32610 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
32620 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
32630 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
32640 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
32650 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
32660 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32670 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
32680 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
32690 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
326a0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
326b0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
326c0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
326d0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
326e0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
326f0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
32700 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32710 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
32720 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
32730 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
32740 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32750 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
32760 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
32770 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
32780 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
32790 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
327a0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
327b0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
327c0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
327d0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
327e0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
327f0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
32800 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
32810 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
32820 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
32830 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
32840 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
32850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32860 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
32870 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
32880 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
32890 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
328a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
328b0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
328c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
328d0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
328e0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
328f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
32900 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
32910 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
32920 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
32930 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
32940 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
32950 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
32960 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
32970 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
32980 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
32990 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
329a0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
329b0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
329c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
329d0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
329e0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
329f0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
32a00 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
32a10 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
32a20 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
32a30 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
32a40 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
32a50 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
32a60 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
32a70 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
32a80 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
32a90 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
32aa0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
32ab0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
32ac0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
32ad0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
32ae0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
32af0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
32b00 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
32b10 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
32b20 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
32b30 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
32b40 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
32b50 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
32b60 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
32b70 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
32b80 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
32b90 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
32ba0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
32bb0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
32bc0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
32bd0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
32be0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
32bf0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
32c00 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32c10 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
32c20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32c30 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
32c40 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
32c50 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
32c60 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
32c70 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
32c80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32c90 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
32ca0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
32cb0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32cc0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32cd0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
32ce0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
32cf0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32d00 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
32d10 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
32d20 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
32d30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
32d40 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
32d50 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
32d60 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
32d70 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
32d80 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
32d90 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
32da0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32db0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32dc0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
32dd0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
32de0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
32df0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
32e00 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
32e10 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
32e20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
32e30 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
32e40 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
32e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32e60 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
32e70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
32e80 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
32e90 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
32ea0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
32eb0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
32ec0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
32ed0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
32ee0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
32ef0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
32f00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32f10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
32f20 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
32f30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
32f40 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
32f50 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
32f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
32f70 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
32f80 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
32f90 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
32fa0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
32fb0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
32fc0 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
32fd0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
32fe0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
32ff0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
33000 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
33010 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
33020 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
33030 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
33040 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
33050 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33060 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
33070 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
33080 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
33090 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
330a0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
330b0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
330c0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
330d0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
330e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
330f0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
33100 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
33110 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
33120 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
33130 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33140 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
33150 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
33160 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
33170 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
33180 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
33190 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
331a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
331b0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
331c0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
331d0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
331e0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
331f0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
33200 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
33210 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
33220 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33230 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
33240 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
33250 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
33260 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
33270 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
33280 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
33290 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
332a0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
332b0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
332c0 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
332d0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
332e0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
332f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33300 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
33310 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
33320 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
33330 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
33340 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
33350 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33360 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
33370 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
33380 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
33390 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
333a0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
333b0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
333c0 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
333d0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
333e0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
333f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
33400 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
33410 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
33420 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33430 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
33440 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
33450 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
33460 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
33470 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
33480 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
33490 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
334a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
334b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
334c0 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
334d0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
334e0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
334f0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
33500 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
33510 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
33520 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
33530 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
33540 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
33550 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
33560 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
33570 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33580 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
33590 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
335a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
335b0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
335c0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
335d0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
335e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
335f0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
33600 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33610 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
33620 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
33630 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
33640 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
33650 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
33660 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
33670 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
33680 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
33690 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
336a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
336b0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
336c0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
336d0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
336e0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
336f0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
33700 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
33710 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
33720 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
33730 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
33740 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
33750 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
33760 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
33770 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
33780 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33790 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
337a0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
337b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
337c0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
337d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
337e0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
337f0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
33800 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
33810 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
33820 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
33830 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
33840 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
33850 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
33860 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
33870 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
33880 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
33890 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
338a0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
338b0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
338c0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
338d0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
338e0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
338f0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
33900 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
33910 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
33920 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
33930 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33940 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33950 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
33960 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
33970 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
33980 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
33990 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
339a0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
339b0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
339c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
339d0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
339e0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
339f0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
33a00 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
33a10 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
33a20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
33a30 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
33a40 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
33a50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33a60 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
33a70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33a80 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
33a90 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
33aa0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
33ab0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
33ac0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
33ad0 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
33ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
33af0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
33b00 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
33b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
33b20 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
33b30 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73   Data.**.** Thes
33b40 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
33b50 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
33b60 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
33b70 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
33b80 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
33b90 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
33ba0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
33bb0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
33bc0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
33bd0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
33be0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
33bf0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
33c00 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
33c10 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
33c20 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
33c30 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
33c40 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
33c50 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
33c60 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
33c70 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
33c80 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
33c90 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
33ca0 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
33cb0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
33cc0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
33cd0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
33ce0 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
33cf0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
33d00 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
33d10 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
33d20 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
33d30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
33d40 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
33d50 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
33d60 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
33d70 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
33d80 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
33d90 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
33da0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
33db0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
33dc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33dd0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
33de0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33df0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
33e00 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
33e10 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
33e20 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
33e30 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
33e40 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
33e50 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
33e60 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
33e70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33e80 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
33e90 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
33ea0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
33eb0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
33ec0 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
33ed0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
33ee0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
33ef0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
33f00 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
33f10 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
33f20 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
33f30 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
33f40 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
33f50 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
33f60 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
33f70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33f80 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
33f90 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
33fa0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
33fb0 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
33fc0 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
33fd0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
33fe0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33ff0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
34000 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
34010 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
34020 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
34030 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
34040 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
34050 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
34060 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
34070 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
34080 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
34090 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74  t NULL,.** SQLit
340a0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
340b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
340c0 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72  ction X with par
340d0 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79  ameter P exactly
340e0 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74  .** once, when t
340f0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
34100 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c  iscarded..** SQL
34110 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64  ite is free to d
34120 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64  iscard the metad
34130 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c  ata at any time,
34140 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e   including: <ul>
34150 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68  .** <li> when th
34160 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
34170 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
34180 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a  er changes, or.*
34190 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c  * <li> when [sql
341a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
341b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
341c0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ze()] is called 
341d0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
341e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  SQL statement, o
341f0 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73  r.** <li> when s
34200 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34210 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
34220 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
34230 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  e parameter, or.
34240 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74  ** <li> during t
34250 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69  he original sqli
34260 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34270 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65  ) call when a me
34280 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c  mory .**      al
34290 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
342a0 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a  ccurs. </ul>)^.*
342b0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61  *.** Note the la
342c0 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72  st bullet in par
342d0 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65  ticular.  The de
342e0 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a  structor X in .*
342f0 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
34300 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d  xdata(C,N,P,X) m
34310 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69  ight be called i
34320 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
34330 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  re the.** sqlite
34340 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34350 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72  interface even r
34360 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73  eturns.  Hence s
34370 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34380 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ta().** should b
34390 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68  e called near th
343a0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e  e end of the fun
343b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
343c0 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20  tion and the.** 
343d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
343e0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ntation should n
343f0 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20  ot make any use 
34400 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71  of P after.** sq
34410 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34420 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  a() has been cal
34430 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  led..**.** ^(In 
34440 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
34450 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
34460 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
34470 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75   calls for.** fu
34480 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
34490 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69  s that are compi
344a0 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74  le-time constant
344b0 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74  s, including lit
344c0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
344d0 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  nd [parameters] 
344e0 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20  and expressions 
344f0 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68  composed from th
34500 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e same.)^.**.** 
34510 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
34520 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34530 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34540 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
34550 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34560 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
34570 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
34580 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
34590 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
345a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
345b0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
345c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
345d0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
345e0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
345f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34600 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
34610 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
34620 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
34630 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
34640 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
34650 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
34660 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
34670 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
34680 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
34690 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
346a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
346b0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
346c0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
346d0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
346e0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
346f0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
34700 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
34710 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
34720 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
34730 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
34740 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
34750 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
34760 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
34770 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
34780 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
34790 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
347a0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
347b0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
347c0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
347d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
347e0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
347f0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
34800 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
34810 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
34820 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
34830 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
34840 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
34850 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74   compilers..*/.t
34860 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
34870 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
34880 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
34890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
348a0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
348b0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
348c0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
348d0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
348e0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
348f0 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
34900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34910 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
34920 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
34930 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
34940 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34950 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
34960 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
34970 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
34980 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
34990 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
349a0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
349b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
349c0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
349d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
349e0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
349f0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
34a00 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
34a10 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
34a20 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
34a30 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
34a40 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
34a50 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
34a60 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
34a70 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
34a80 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
34a90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34aa0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
34ab0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
34ac0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
34ad0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
34ae0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
34af0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34b00 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
34b10 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34b20 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
34b30 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
34b40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34b50 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
34b60 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
34b70 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
34b80 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
34b90 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
34ba0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
34bb0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
34bc0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
34bd0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
34be0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
34bf0 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
34c00 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
34c10 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
34c20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34c30 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
34c40 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
34c50 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
34c60 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
34c70 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
34c80 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
34c90 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34ca0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
34cb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
34cc0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
34cd0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
34ce0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
34cf0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34d00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
34d10 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
34d20 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
34d30 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
34d40 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34d50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34d60 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
34d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34d80 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
34d90 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
34da0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
34db0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
34dc0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
34dd0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
34de0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
34df0 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
34e00 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
34e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34e20 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
34e30 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34e40 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
34e50 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
34e60 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
34e70 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
34e80 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
34e90 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
34ea0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
34eb0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
34ec0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
34ed0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
34ee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ef0 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
34f00 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
34f10 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
34f20 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
34f30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34f40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
34f50 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34f60 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
34f70 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
34f80 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
34f90 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
34fa0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
34fb0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
34fc0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
34fd0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
34fe0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
34ff0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35000 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
35010 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35020 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
35030 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
35040 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
35050 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
35060 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
35070 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
35080 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
35090 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
350a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
350b0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
350c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
350d0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
350e0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
350f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
35100 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
35110 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
35120 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
35130 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
35140 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
35150 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
35160 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
35170 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
35180 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
35190 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
351a0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
351b0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
351c0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
351d0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
351e0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
351f0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
35200 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
35210 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
35220 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
35230 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
35240 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
35250 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
35260 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
35270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35280 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
35290 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
352a0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
352b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
352c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
352d0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
352e0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
352f0 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
35300 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
35310 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
35320 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
35330 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
35340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35350 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35360 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
35370 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
35380 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
35390 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
353a0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
353b0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
353c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
353d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
353e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
353f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35400 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
35410 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35420 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
35430 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
35440 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
35450 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
35460 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
35470 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35480 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
35490 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
354a0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
354b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
354c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
354d0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
354e0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
354f0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
35500 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
35510 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
35520 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35530 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
35540 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35550 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35560 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35570 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35580 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
35590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
355a0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
355b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
355c0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
355d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
355e0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
355f0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
35600 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
35610 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
35620 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
35630 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35640 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
35650 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
35660 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
35670 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
35680 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
35690 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
356a0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
356b0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
356c0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
356d0 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ely..** ^The sql
356e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
356f0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
35700 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
35710 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70  alue of an.** ap
35720 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35730 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35740 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69   a text string i
35750 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  n an encoding.**
35760 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
35770 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73  e fifth (and las
35780 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  t) parameter, wh
35790 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a  ich must be one.
357a0 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ** of [SQLITE_UT
357b0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
357c0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
357d0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
357e0 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e  E_UTF16LE]..** ^
357f0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
35800 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
35810 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
35820 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
35830 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
35840 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35850 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35860 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
35870 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
35880 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35890 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
358a0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
358b0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
358c0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
358d0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
358e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
358f0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
35900 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
35910 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
35920 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
35930 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35940 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
35950 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
35960 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
35970 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
35980 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
35990 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
359a0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
359b0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
359c0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
359d0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
359e0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
359f0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
35a00 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
35a10 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
35a20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
35a30 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
35a40 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
35a50 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
35a60 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
35a70 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
35a80 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
35a90 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
35aa0 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
35ab0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
35ac0 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
35ad0 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
35ae0 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
35af0 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
35b00 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
35b10 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
35b20 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
35b30 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
35b40 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
35b50 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
35b60 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
35b70 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
35b80 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
35b90 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
35ba0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
35bb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35bc0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35bd0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
35be0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
35bf0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
35c00 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
35c10 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
35c20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
35c30 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
35c40 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
35c50 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
35c60 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
35c70 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
35c80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35c90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35ca0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35cb0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35cc0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
35cd0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35ce0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
35cf0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
35d00 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
35d10 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
35d20 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
35d30 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
35d40 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
35d50 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
35d60 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
35d70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
35d80 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
35d90 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
35da0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
35db0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
35dc0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
35dd0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35de0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35df0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35e00 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35e10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
35e20 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
35e30 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
35e40 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
35e50 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
35e60 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
35e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
35e80 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
35e90 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
35ea0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35eb0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
35ec0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
35ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35ee0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
35ef0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
35f00 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
35f10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35f20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
35f30 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
35f40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35f50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
35f60 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
35f70 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
35f80 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
35f90 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
35fa0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
35fb0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
35fc0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
35fd0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
35fe0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
35ff0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
36000 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
36010 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
36020 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
36030 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36040 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
36050 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
36060 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36070 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36080 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
36090 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
360a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
360b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
360c0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
360d0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
360e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
360f0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
36100 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
36110 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
36120 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
36130 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
36140 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
36150 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
36160 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
36170 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
36180 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36190 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
361a0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
361b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
361c0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
361d0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
361e0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
361f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36200 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
36210 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36220 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36230 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36240 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36250 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
36260 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  xt*,const void*,
36270 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76  sqlite3_uint64,v
36280 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
36290 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
362a0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
362b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
362c0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
362d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
362e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
362f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
36300 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
36310 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36320 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36330 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36340 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36350 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36360 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
36370 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36390 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
363a0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
363b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
363c0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
363d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
363e0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
363f0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
36400 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36410 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36420 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
36430 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36440 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
36450 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36460 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
36470 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
36480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36490 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
364a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
364b0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
364c0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
364d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
364e0 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt64(sqlite3_con
364f0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36500 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
36510 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
36520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
36530 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
36540 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
36550 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ding);.void sqli
36560 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36570 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
36580 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36590 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
365a0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
365b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
365c0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
365d0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
365e0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
365f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36600 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36610 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
36620 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36630 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
36640 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
36650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
36660 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
36670 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
36680 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
36690 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
366a0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
366b0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
366c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
366d0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
366e0 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
366f0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
36700 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
36710 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
36720 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
36730 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
36740 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36750 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
36760 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
36770 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
36780 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
36790 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
367a0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
367b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
367c0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
367d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
367e0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
367f0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
36800 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
36810 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
36820 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36830 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
36840 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
36850 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
36860 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
36870 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
36880 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
36890 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
368a0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
368b0 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
368c0 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
368d0 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
368e0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
368f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
36900 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
36910 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
36920 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
36930 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
36940 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
36950 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
36960 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
36970 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
36980 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
36990 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
369a0 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
369b0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
369c0 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
369d0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
369e0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
369f0 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
36a00 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
36a10 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
36a20 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
36a30 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
36a40 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
36a50 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
36a60 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
36a70 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
36a80 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
36a90 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
36aa0 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
36ab0 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
36ac0 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
36ad0 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
36ae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
36af0 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
36b00 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
36b10 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
36b20 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
36b30 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
36b40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
36b50 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
36b60 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
36b70 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
36b80 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
36b90 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
36ba0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
36bb0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36bc0 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
36bd0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36be0 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
36bf0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
36c00 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
36c10 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
36c20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
36c30 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
36c40 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
36c50 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
36c60 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
36c70 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
36c80 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
36c90 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
36ca0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
36cb0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
36cc0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36cd0 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
36ce0 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
36cf0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36d00 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
36d10 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
36d20 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
36d30 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
36d40 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
36d50 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
36d60 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
36d70 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
36d80 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
36d90 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
36da0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
36db0 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
36dc0 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
36dd0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
36de0 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
36df0 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
36e00 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36e10 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
36e20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
36e30 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
36e40 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
36e50 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
36e60 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
36e70 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
36e80 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
36e90 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
36ea0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
36eb0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36ec0 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
36ed0 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
36ee0 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
36ef0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
36f00 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
36f10 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36f20 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
36f30 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
36f40 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
36f50 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
36f60 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
36f70 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
36f80 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
36f90 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
36fa0 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
36fb0 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
36fc0 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
36fd0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36fe0 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
36ff0 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
37000 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
37010 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
37020 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
37030 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
37040 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
37050 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
37060 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
37070 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
37080 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
37090 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
370a0 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
370b0 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
370c0 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
370d0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
370e0 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
370f0 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
37100 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
37110 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37120 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
37130 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
37140 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
37150 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
37160 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37170 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37180 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
37190 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
371a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
371b0 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
371c0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
371d0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
371e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
371f0 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
37200 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37210 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
37220 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
37230 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
37240 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
37250 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
37260 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
37270 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
37280 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
37290 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
372a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
372b0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
372c0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
372d0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
372e0 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
372f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
37300 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
37310 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
37320 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37330 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
37340 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
37350 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
37360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
37370 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37380 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
37390 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
373a0 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
373b0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
373c0 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
373d0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
373e0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
373f0 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
37400 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
37410 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
37420 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
37430 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
37440 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
37450 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
37460 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
37470 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
37480 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
37490 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
374a0 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
374b0 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
374c0 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
374d0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
374e0 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
374f0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37500 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
37510 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37520 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
37530 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37540 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
37550 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37560 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
37570 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37580 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
37590 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
375a0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
375b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
375c0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
375d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
375e0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
375f0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
37600 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
37610 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
37620 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
37630 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
37640 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37650 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37660 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
37670 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
37680 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37690 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
376a0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
376b0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
376c0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
376d0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
376e0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
376f0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
37700 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37710 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
37720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
37730 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
37740 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
37750 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
37760 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
37770 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37780 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
37790 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
377a0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
377b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
377c0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
377d0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
377e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
377f0 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
37800 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
37810 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
37820 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
37830 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
37840 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
37850 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
37860 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
37870 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37880 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
37890 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
378a0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
378b0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
378c0 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
378d0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
378e0 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
378f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37900 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
37910 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
37920 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
37930 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
37940 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
37950 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
37960 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
37970 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
37980 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
37990 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
379a0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
379b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
379c0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
379d0 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
379e0 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
379f0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
37a00 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
37a10 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37a20 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
37a30 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37a40 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
37a50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
37a60 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
37a70 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
37a80 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
37a90 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
37aa0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
37ab0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
37ac0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
37ad0 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
37ae0 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
37af0 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
37b00 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
37b10 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
37b20 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
37b30 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
37b40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
37b50 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
37b60 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
37b70 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
37b80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
37b90 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
37ba0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
37bb0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
37bc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37bd0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
37be0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37bf0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
37c00 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37c10 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
37c20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37c30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37c40 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
37c50 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
37c60 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
37c70 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
37c80 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
37c90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
37ca0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
37cb0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
37cc0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
37cd0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
37ce0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
37cf0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
37d00 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
37d10 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
37d20 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
37d30 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
37d40 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
37d50 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
37d60 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
37d70 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
37d80 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
37d90 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
37da0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
37db0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
37dc0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
37dd0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
37de0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
37df0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37e10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
37e20 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
37e30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37e40 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37e50 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
37e60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  ;.int sqlite3_ke
37e70 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
37e80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
37e90 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
37ea0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
37eb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37ec0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37ed0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
37ee0 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
37ef0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37f00 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37f10 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
37f20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
37f30 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
37f40 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
37f50 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
37f60 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
37f70 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
37f80 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
37f90 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
37fa0 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
37fb0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
37fc0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
37fd0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
37fe0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
37ff0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
38000 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
38010 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
38020 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
38030 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
38040 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
38050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38060 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
38070 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
38080 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
38090 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
380a0 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
380b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  );.int sqlite3_r
380c0 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  ekey_v2(.  sqlit
380d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
380e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
380f0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
38100 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
38110 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
38120 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
38130 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
38140 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
38150 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
38160 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
38170 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
38180 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
38190 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
381a0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
381b0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
381c0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
381d0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
381e0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
381f0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
38200 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
38210 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
38220 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
38230 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
38240 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
38250 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
38260 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
38270 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
38280 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
38290 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
382a0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
382b0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
382c0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
382d0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
382e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
382f0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
38300 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
38310 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
38320 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
38330 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
38340 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
38350 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
38360 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
38370 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
38380 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
38390 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
383a0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
383b0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
383c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
383d0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
383e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
383f0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
38400 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
38410 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
38420 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
38430 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
38440 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
38450 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
38460 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
38470 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
38480 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
38490 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
384a0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
384b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
384c0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
384d0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
384e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
384f0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
38500 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
38510 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
38520 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
38530 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
38540 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
38550 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
38560 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
38570 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
38580 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
38590 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
385a0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
385b0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
385c0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
385d0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
385e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
385f0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
38600 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
38610 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
38620 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
38630 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
38640 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
38650 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
38660 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38670 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
38680 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
38690 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
386a0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
386b0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
386c0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
386d0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
386e0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
386f0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
38700 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
38710 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
38720 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
38730 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
38740 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
38750 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
38760 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
38770 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
38780 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
38790 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
387a0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
387b0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
387c0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
387d0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
387e0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
387f0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
38800 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ory..**.** Appli
38810 63 61 74 69 6f 6e 73 20 61 72 65 20 73 74 72 6f  cations are stro
38820 6e 67 6c 79 20 64 69 73 63 6f 75 72 61 67 65 64  ngly discouraged
38830 20 66 72 6f 6d 20 75 73 69 6e 67 20 74 68 69 73   from using this
38840 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
38850 2e 0a 2a 2a 20