/ Hex Artifact Content
Login

Artifact d4abdfeea75b91d505998e14c6b98b240ce4eb31:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5600: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5610: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5620: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5640: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5650: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5660: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5680: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5690: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
56a0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
56c0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
56e0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5700: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
5710: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5720: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
5730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5740: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5750: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5760: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5780: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5790: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
57a0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
57b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57c0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
57d0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
57e0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
57f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5800: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5810: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5820: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5830: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5840: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5850: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5860: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5890: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
58a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
58b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
58c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
58d0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
58e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
58f0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5910: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5920: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5930: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5940: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5950: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5960: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5990: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59a0: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59c0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
59d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
59e0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
59f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a00: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a20: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5a30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a40: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5a50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a60: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a70: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5aa0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ab0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5ad0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5ae0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5af0: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5b00: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5b10: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b20: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5b30: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5b40: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5b50: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (2<<8))../*.**
5b60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5b70: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5b80: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5b90: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5ba0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5bb0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5bc0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5bd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5be0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5bf0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5c00: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5c10: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
5c20: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
5c30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5c40: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5c50: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5c60: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
5c70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5c80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5c90: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5ca0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5cb0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
5cc0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5cd0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5ce0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d00: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
5d10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5d20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5d30: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5d40: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5d50: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
5d60: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5d70: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5d80: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5d90: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
5da0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5db0: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
5dc0: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
5dd0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
5de0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5df0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
5e00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e10: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e30: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e40: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
5e50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e60: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
5e70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5ea0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5eb0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
5ec0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ef0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
5f00: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f10: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5f20: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5f30: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
5f40: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5f60: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5f70: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
5f80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5fa0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5fb0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
5fc0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5fd0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5fe0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
5ff0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
6000: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
6030: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
6040: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6050: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
6060: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6070: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
6080: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6090: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60a0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
60b0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
60c0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60f0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
6100: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
6110: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6140: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
6150: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
6160: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6180: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6190: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
61a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
61b0: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
61c0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
61d0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
61e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
61f0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
6200: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
6210: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
6220: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6230: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6240: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6260: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6270: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6280: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6290: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
62a0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
62b0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
62c0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
62d0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
62e0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
62f0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6300: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6310: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6320: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6340: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6350: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6360: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6370: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
63a0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
63b0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
63c0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
63d0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
63e0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
63f0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6400: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6410: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6420: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6430: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6440: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6450: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6460: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6470: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6480: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6490: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
64a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
64b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
64c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
64d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
64e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
64f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6500: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6510: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6520: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6530: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6540: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6550: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6560: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6570: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6580: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6590: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
65a0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
65b0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
65c0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
65d0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
65e0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
65f0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6600: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6610: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6620: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6630: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6640: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6650: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6660: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6670: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6680: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
6690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
66a0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
66b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
66c0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
66d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66e0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
66f0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6710: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6720: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6730: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6740: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6760: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6770: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6780: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6790: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
67a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
67c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
67d0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67f0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6800: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6840: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6870: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6890: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68b0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
68d0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
68e0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6900: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6910: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6940: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6950: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
6960: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6970: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6980: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6990: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
69a0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
69b0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
69c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
69d0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
69e0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
69f0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6a00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6a10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6a20: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6a30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6a40: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6a60: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6a80: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6a90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6aa0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6ab0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6ac0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6ad0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6af0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6b00: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6b10: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6b20: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6b30: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6b40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6b50: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6b60: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6b70: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6b80: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6b90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6ba0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6bb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6bc0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6bd0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6be0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6bf0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6c00: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6c10: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6c20: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6c30: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6c40: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6c50: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6c60: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6c70: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6c80: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6c90: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6ca0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6cb0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6cc0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6cd0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6ce0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6cf0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6d00: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6d10: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6d20: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6d30: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6d40: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d50: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6d60: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6d70: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
6d80: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6d90: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6da0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6db0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6dc0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6dd0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6de0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6df0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6e00: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6e10: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6e20: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
6e30: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
6e40: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
6e50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6e60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6e70: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6e80: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6e90: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6ea0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6eb0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6ec0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6ed0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6ee0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6ef0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6f00: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6f10: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6f20: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6f30: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
6f40: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
6f50: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
6f60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6f70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6f80: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6f90: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6fa0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6fb0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6fc0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6fd0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6fe0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7000: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7010: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7020: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7030: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7040: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7050: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7060: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7070: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7080: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7090: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
70a0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
70b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
70c0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
70d0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
70e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
70f0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7100: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7110: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7120: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7130: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7140: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7150: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7160: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7170: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7180: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7190: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
71a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
71b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
71c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
71d0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
71e0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
71f0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7200: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7210: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7220: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7230: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7240: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7250: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7260: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7270: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7280: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7290: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
72a0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
72b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
72c0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
72d0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
72e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
72f0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7300: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7310: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7320: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7330: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7340: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7350: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7360: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7370: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7380: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
73a0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
73b0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
73c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
73d0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
73e0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
73f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7400: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7410: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7430: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7440: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7450: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7460: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7470: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7480: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7490: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
74a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
74b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
74c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
74d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
74e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
74f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7500: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7510: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7520: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7530: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7540: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7550: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7560: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7570: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7580: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7590: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
75a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
75b0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
75c0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
75d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
75e0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
75f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7610: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7620: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7630: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7640: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7650: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7660: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7670: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7680: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7690: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
76a0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
76b0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
76c0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
76d0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
76e0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
76f0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7700: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7710: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7720: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7730: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7740: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7750: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7760: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7770: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7780: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7790: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
77a0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
77b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
77c0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
77d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
77e0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
77f0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7800: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7810: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7820: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7830: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7840: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7850: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7860: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7870: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7880: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7890: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
78a0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
78b0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
78c0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
78d0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
78e0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
78f0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7900: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7910: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7920: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7930: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7940: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7950: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7960: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7970: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7980: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7990: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
79a0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
79b0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
79c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
79d0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
79e0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
79f0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7a00: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7a10: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7a20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7a30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7a40: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7a50: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7a60: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7a70: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7a80: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7a90: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7aa0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7ab0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7ac0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7ad0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7ae0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7af0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7b00: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7b10: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7b20: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7b30: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7b40: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7b50: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7b60: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7b70: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7b80: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7b90: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7ba0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7bb0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7bc0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7bd0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7be0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7bf0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7c00: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7c10: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7c20: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7c30: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7c40: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7c50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7c60: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7c70: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7c80: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7c90: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7ca0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7cb0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7cc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7cd0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7ce0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7cf0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7d00: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7d10: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7d20: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7d30: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7d40: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7d50: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7d60: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7d70: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7d80: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7d90: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7da0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7db0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7dc0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7dd0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7de0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7df0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7e00: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7e10: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7e20: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7e30: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7e40: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7e50: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7e70: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7e80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7e90: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7eb0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7ec0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ed0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7ee0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ef0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f10: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f30: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f50: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7f60: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f70: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7f80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7f90: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7fa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7fb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7fc0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7fd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7fe0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7ff0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
8000: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
8010: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8020: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8030: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8040: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8050: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8060: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8070: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8080: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8090: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
80a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
80b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
80c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
80d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
80e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
80f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8100: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8110: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8120: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8130: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8140: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8150: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8160: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8170: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8180: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8190: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
81a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
81b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
81c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
81d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
81e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
81f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8200: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8210: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8220: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8230: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8240: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8250: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8260: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8270: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8280: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8290: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
82a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
82b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
82c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
82d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
82e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
82f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8300: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8310: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8320: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8330: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8350: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8360: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8370: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8380: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
83a0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
83b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
83c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
83d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
83e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
83f0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8400: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8410: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8420: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8430: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8440: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8450: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8460: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8470: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8480: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8490: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
84a0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
84b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
84c0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
84d0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
84e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
84f0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8510: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8520: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8530: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8540: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8550: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8560: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8570: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8580: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8590: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
85a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85b0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
85c0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
85d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
85e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
85f0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8600: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8610: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8620: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8630: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8640: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8650: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8660: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8670: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8680: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8690: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
86a0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
86b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
86c0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
86d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
86e0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
86f0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8700: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8710: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8720: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8730: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8740: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8750: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8760: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8770: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8780: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8790: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
87a0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
87b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
87c0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
87d0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
87e0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
87f0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8800: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8810: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8820: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8830: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8840: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
8850: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8860: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8870: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8880: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8890: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
88a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
88b0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
88c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
88d0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
88e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
88f0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8900: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8910: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8920: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8930: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8940: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8950: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8960: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8970: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8980: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8990: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
89a0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
89b0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
89c0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
89d0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
89e0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
89f0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8a00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8a10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8a20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8a30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8a40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8a50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8a60: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8a70: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8a80: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8a90: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8aa0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8ac0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8ad0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8ae0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8af0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8b00: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8b10: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8b20: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8b30: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8b40: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8b50: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8b60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8b70: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8b80: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8b90: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8ba0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8bb0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8bc0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8bd0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8be0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8bf0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8c00: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8c10: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8c20: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8c30: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8c40: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8c50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8c60: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8c70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8c80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8c90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8ca0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8cb0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8cc0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8cd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8ce0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
8cf0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
8d00: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
8d10: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
8d20: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8d30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8d40: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
8d50: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
8d60: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
8d70: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
8d80: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
8d90: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
8da0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
8db0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
8dc0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
8dd0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
8de0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
8df0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
8e00: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
8e10: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
8e20: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
8e30: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
8e40: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
8e50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8e60: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
8e70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8e80: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8e90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ea0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
8eb0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8ec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8ed0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8ee0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8ef0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8f00: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8f20: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8f30: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8f40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8f50: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
8f60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8f70: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
8f80: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
8f90: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8fa0: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20  TTED] opcode is 
8fb0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
8fc0: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ally by.** SQLit
8fd0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c  e and sent to al
8fe0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65  l VFSes in place
8ff0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68   of a call to th
9000: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a  e xSync method.*
9010: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  * when the datab
9020: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
9030: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  as [PRAGMA synch
9040: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f  ronous] set to O
9050: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70  FF.)^.** Some sp
9060: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9070: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9080: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65   in order to ope
9090: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a  rate correctly.*
90a0: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73  * when [PRAGMA s
90b0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
90c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
90d0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74  OFF] is set, but
90e0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20   most .** VFSes 
90f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9100: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75   signal and shou
9110: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9120: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  re this opcode..
9130: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
9140: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9160: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9170: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20  is.** opcode as 
9180: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
9190: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
91a0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
91b0: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74  lized VFSes.** t
91c0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
91d0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
91e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
91f0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9200: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9210: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9220: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9230: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9240: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9250: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9260: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9270: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9280: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9290: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
92a0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
92b0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
92c0: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
92d0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
92e0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
92f0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9300: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9310: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9320: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9330: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9340: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9350: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9360: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9370: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9380: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9390: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
93a0: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
93b0: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
93c0: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
93d0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
93e0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
93f0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9400: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9410: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9420: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9430: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9440: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9450: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9460: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9470: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9480: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9490: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
94a0: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
94b0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
94c0: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
94d0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
94e0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
94f0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9500: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9510: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9520: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9530: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9540: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9550: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9560: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9570: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9580: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9590: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
95a0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
95b0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
95c0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
95d0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
95e0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
95f0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9600: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9610: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9620: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9630: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9640: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9660: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9670: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9680: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9690: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
96a0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
96b0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
96c0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
96d0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
96e0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
96f0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9700: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9710: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9720: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9730: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9740: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9750: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9770: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9780: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9790: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
97a0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
97b0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
97c0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
97d0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
97e0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
97f0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9800: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9810: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9820: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9830: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9840: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9850: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9860: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9870: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9880: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9890: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
98a0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
98b0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
98c0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
98d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
98e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
98f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9900: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9910: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9920: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9930: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9940: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9950: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9960: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9970: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9980: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9990: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
99a0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
99b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
99c0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
99d0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
99e0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
99f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9a00: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9a10: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9a20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9a30: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9a40: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9a50: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9a60: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9a70: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9a80: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9a90: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9aa0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9ab0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9ac0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9ad0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9ae0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9af0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9b00: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9b10: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9b20: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9b30: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b40: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9b50: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9b60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9b70: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9b80: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9b90: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
9ba0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
9bb0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
9bc0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
9bd0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9be0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9bf0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9c00: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9c10: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9c20: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
9c30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9c40: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
9c50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9c60: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
9c70: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
9c80: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
9c90: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
9ca0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
9cb0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
9cc0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
9cd0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
9ce0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
9cf0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
9d00: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
9d10: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
9d20: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
9d30: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
9d40: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
9d50: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
9d60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9d70: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9d80: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9d90: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9da0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
9db0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
9dc0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
9dd0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
9de0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
9df0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
9e00: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
9e10: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
9e20: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
9e30: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
9e40: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
9e50: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
9e60: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
9e70: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
9e80: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
9e90: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
9ea0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
9eb0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
9ec0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9ed0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
9ee0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
9ef0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
9f00: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
9f10: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
9f20: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
9f30: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
9f40: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
9f50: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
9f60: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
9f70: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
9f80: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
9f90: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
9fa0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
9fb0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
9fc0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
9fd0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9fe0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
9ff0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a000: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a010: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a020: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a030: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a040: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a050: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a060: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a070: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a080: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a090: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a0a0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a0b0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a0c0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a0d0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a0e0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a0f0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a100: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a110: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a120: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a130: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a140: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a150: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a160: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a170: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a180: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a190: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a1a0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a1b0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a1c0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a1d0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a1e0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a1f0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a200: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a210: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a220: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a230: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a240: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a250: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a260: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a270: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a280: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a290: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a2a0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a2b0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a2c0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a2d0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a2e0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a2f0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a300: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a310: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a320: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a330: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a340: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a350: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a370: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a380: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a390: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a3a0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a3b0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a3c0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a3d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a3e0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a3f0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a400: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a410: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a420: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a430: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a440: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a450: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a460: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a470: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a480: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a490: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a4a0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a4b0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a4c0: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a4d0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a4e0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a4f0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a500: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a510: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a520: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
a530: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
a540: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
a550: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
a560: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
a570: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
a580: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
a590: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a5a0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a5b0: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
a5c0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
a5d0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
a5e0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
a5f0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
a600: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
a610: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
a620: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
a630: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
a640: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
a650: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a660: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
a670: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
a680: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
a690: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
a6a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
a6b0: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
a6c0: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
a6d0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
a6e0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
a6f0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
a700: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
a710: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
a720: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
a730: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
a740: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
a750: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
a760: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
a770: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
a780: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
a790: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
a7a0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
a7b0: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
a7c0: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
a7d0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
a7e0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
a7f0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
a800: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
a810: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
a820: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
a830: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
a840: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
a850: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
a860: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
a870: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
a880: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
a890: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
a8a0: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
a8b0: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
a8c0: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
a8d0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
a8e0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
a8f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
a900: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
a910: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
a920: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
a930: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
a940: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
a950: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
a960: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
a970: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
a980: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
a990: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
a9a0: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
a9b0: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
a9c0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
a9d0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
a9e0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
a9f0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aa00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aa10: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aa20: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
aa30: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
aa40: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
aa50: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aa60: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
aa70: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
aa80: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
aa90: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
aaa0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
aab0: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
aac0: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
aad0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
aae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
aaf0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
ab10: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
ab20: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
ab30: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
ab40: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
ab50: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
ab60: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
ab70: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
ab80: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
ab90: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
aba0: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
abb0: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
abc0: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
abd0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
abe0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
abf0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
ac00: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
ac10: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
ac20: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
ac30: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
ac40: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
ac50: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
ac60: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
ac70: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
ac80: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
ac90: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
aca0: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
acb0: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
acc0: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
acd0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
ace0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
acf0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
ad00: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
ad10: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
ad20: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
ad30: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ..**.** </ul>.*/
ad40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ad50: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
ad60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
ad70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
ad80: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ad90: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
ada0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
adb0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
adc0: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
add0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
ade0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
adf0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
ae00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ae10: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
ae20: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
ae30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ae40: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
ae50: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
ae60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ae70: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
ae80: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
ae90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
aea0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
aeb0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
aec0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
aed0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
aee0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
aef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
af00: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
af10: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
af20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
af30: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
af40: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
af50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
af60: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
af70: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
af80: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
af90: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
afa0: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
afb0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
afc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
afd0: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
afe0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
aff0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
b000: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
b010: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b020: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
b030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b040: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
b050: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
b060: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b070: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
b080: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
b090: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
b0a0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
b0b0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
b0c0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
b0d0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
b0e0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
b0f0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
b100: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
b110: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
b120: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
b130: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
b140: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
b150: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
b160: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
b170: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
b180: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
b190: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
b1a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
b1b0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
b1c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
b1d0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
b1e0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
b1f0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b200: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
b210: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
b220: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
b230: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b240: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
b250: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
b260: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
b270: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
b280: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
b290: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
b2a0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
b2b0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
b2c0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
b2d0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
b2e0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
b2f0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
b300: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
b310: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
b320: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
b330: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
b340: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
b350: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
b360: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
b370: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
b380: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
b390: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
b3a0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
b3b0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
b3c0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
b3d0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
b3e0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
b3f0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
b400: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
b410: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
b420: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
b430: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
b440: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
b450: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
b460: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
b470: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
b480: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
b490: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
b4a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b4b0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
b4c0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
b4d0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
b4e0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
b4f0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
b500: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
b510: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
b520: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
b530: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
b540: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
b550: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
b560: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
b570: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
b580: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
b590: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
b5a0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
b5b0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
b5c0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
b5d0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
b5e0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
b5f0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
b600: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
b610: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
b620: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
b630: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
b640: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b650: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
b660: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
b670: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
b680: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
b690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
b6a0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
b6b0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
b6c0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
b6d0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
b6e0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
b6f0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
b700: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
b710: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
b720: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
b730: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
b740: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
b750: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
b760: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
b770: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
b780: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
b790: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
b7a0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
b7b0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
b7c0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
b7d0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
b7e0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
b7f0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
b800: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
b810: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
b820: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
b830: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
b840: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
b850: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
b860: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
b870: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
b880: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
b890: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
b8a0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
b8b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
b8c0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
b8d0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
b8e0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
b8f0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
b900: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
b910: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
b920: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
b930: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
b940: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
b950: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
b960: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
b970: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
b980: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
b990: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
b9a0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
b9b0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
b9c0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
b9d0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
b9e0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
b9f0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
ba00: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
ba10: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
ba20: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
ba30: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
ba40: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
ba50: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
ba60: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
ba70: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
ba80: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
ba90: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
baa0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
bab0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
bac0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
bad0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
bae0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
baf0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
bb00: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
bb10: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
bb20: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
bb30: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
bb40: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
bb50: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
bb60: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
bb70: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
bb80: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bb90: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
bba0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
bbb0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
bbc0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
bbd0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
bbe0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
bbf0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
bc00: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
bc10: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
bc20: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
bc30: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
bc40: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
bc50: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
bc60: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
bc70: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
bc80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
bc90: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
bca0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
bcb0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
bcc0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
bcd0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
bce0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
bcf0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
bd00: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
bd10: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
bd20: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
bd30: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
bd40: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
bd50: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
bd60: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
bd70: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
bd80: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
bd90: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
bda0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
bdb0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
bdc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
bdd0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
bde0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
bdf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
be00: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
be10: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
be20: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
be30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
be40: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
be50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
be60: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
be70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
be80: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
be90: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
bea0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
beb0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
bec0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
bed0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
bee0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
bef0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
bf00: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
bf10: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
bf20: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
bf30: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
bf40: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
bf50: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
bf60: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
bf70: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
bf80: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
bf90: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
bfa0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
bfb0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
bfc0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
bfd0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
bfe0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
bff0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c000: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c010: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c020: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c030: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c040: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c050: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
c060: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
c070: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
c080: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
c090: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
c0a0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
c0b0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
c0c0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
c0d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
c0e0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
c0f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
c100: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
c110: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
c120: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
c130: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c140: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
c150: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c160: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
c170: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
c180: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c190: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
c1a0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
c1b0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
c1c0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
c1d0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
c1e0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c1f0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
c200: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
c210: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
c220: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
c230: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
c240: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
c250: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
c260: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
c270: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
c280: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
c290: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
c2a0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
c2b0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
c2c0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
c2d0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
c2e0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
c2f0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
c300: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
c310: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
c320: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
c330: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
c340: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
c350: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
c360: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
c370: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
c380: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
c390: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
c3a0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
c3b0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
c3c0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
c3d0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
c3e0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
c3f0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
c400: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
c410: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
c420: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
c430: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
c440: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
c450: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
c460: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
c470: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
c480: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
c490: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
c4a0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
c4b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
c4c0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
c4d0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
c4e0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
c4f0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
c500: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
c510: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
c520: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
c530: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
c540: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
c550: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
c560: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
c570: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
c580: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
c590: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
c5a0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
c5b0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
c5c0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
c5d0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
c5e0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
c5f0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
c600: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
c610: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
c620: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
c630: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
c640: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
c650: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
c660: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
c670: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
c680: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
c690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
c6a0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
c6b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
c6c0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
c6d0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
c6e0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
c6f0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
c700: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
c710: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c720: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
c730: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
c740: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
c750: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
c760: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
c770: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
c780: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
c790: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
c7a0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
c7b0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
c7c0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
c7d0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
c7e0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
c7f0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
c800: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
c810: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
c820: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
c830: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
c840: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
c850: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
c860: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
c870: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
c880: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
c890: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
c8a0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
c8b0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
c8c0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
c8d0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
c8e0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
c8f0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
c900: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
c910: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
c920: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
c930: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
c940: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
c950: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
c960: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
c970: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
c980: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
c990: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
c9a0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
c9b0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
c9c0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
c9d0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
c9e0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
c9f0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
ca00: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
ca10: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
ca20: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
ca30: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
ca40: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
ca50: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
ca60: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
ca70: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
ca80: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
ca90: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
caa0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
cab0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
cac0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
cad0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
cae0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
caf0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
cb00: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
cb10: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
cb20: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
cb30: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
cb40: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
cb50: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
cb60: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
cb70: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
cb80: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
cb90: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
cba0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
cbb0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
cbc0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cbd0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
cbe0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
cbf0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
cc00: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
cc10: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
cc20: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
cc30: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
cc40: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
cc50: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
cc60: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
cc70: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cc80: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
cc90: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
cca0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
ccb0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
ccc0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
ccd0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
cce0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
ccf0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
cd00: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
cd10: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
cd20: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
cd30: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
cd40: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
cd50: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
cd60: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
cd70: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
cd80: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
cd90: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
cda0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
cdb0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
cdc0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
cdd0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
cde0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
cdf0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
ce00: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
ce10: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
ce20: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
ce30: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
ce40: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
ce50: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
ce60: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
ce70: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
ce80: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
ce90: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
cea0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
ceb0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
cec0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
ced0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
cee0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
cef0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
cf00: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
cf10: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
cf20: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
cf30: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
cf40: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
cf50: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
cf60: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
cf70: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
cf80: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
cf90: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
cfa0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
cfb0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
cfc0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
cfd0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
cfe0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
cff0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d000: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d010: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d020: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d030: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d040: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d050: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
d060: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
d070: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
d080: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
d090: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d0a0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
d0b0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
d0c0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
d0d0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
d0e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
d0f0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
d100: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
d110: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
d120: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
d130: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
d140: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
d150: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
d160: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
d170: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
d180: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
d190: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
d1a0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
d1b0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
d1c0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
d1d0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
d1e0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
d1f0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
d200: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
d210: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
d220: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
d230: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
d240: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
d250: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
d260: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
d270: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
d280: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
d290: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d2a0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d2b0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
d2c0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
d2d0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
d2e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
d2f0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
d300: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d310: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
d320: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
d330: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
d340: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d350: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
d360: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
d370: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
d380: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
d390: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d3a0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
d3b0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
d3c0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
d3d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d3e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
d3f0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
d400: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
d410: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
d420: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
d430: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
d440: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
d450: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
d460: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
d470: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
d480: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
d490: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
d4a0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
d4b0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d4c0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
d4d0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
d4e0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
d4f0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
d500: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
d510: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d520: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d530: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
d540: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
d550: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d560: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
d570: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d580: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d590: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
d5a0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d5b0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
d5c0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
d5d0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
d5e0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
d5f0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
d600: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d610: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
d620: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
d630: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
d640: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
d650: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
d660: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
d670: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d680: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
d690: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
d6a0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
d6b0: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
d6c0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
d6d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d6e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d6f0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
d700: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
d710: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
d720: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
d730: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d740: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
d750: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
d760: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
d770: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d790: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
d7a0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
d7b0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
d7c0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
d7d0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d7e0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
d7f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
d800: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
d810: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
d820: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
d830: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
d840: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
d850: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
d860: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
d870: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
d880: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
d890: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
d8a0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
d8b0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
d8c0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
d8d0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
d8e0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
d8f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
d900: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
d910: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
d920: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
d930: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
d940: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
d950: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
d960: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
d970: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
d980: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
d990: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
d9a0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
d9b0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
d9c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
d9d0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
d9e0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
d9f0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
da00: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
da10: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
da20: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
da30: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
da40: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
da50: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
da60: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
da70: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
da80: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
da90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
daa0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
dab0: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
dac0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
dad0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
dae0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
daf0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
db00: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
db10: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
db20: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
db30: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
db40: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
db50: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
db60: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
db70: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
db80: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
db90: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
dba0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
dbb0: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
dbc0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
dbd0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
dbe0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
dbf0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
dc00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
dc10: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
dc20: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
dc30: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
dc40: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
dc50: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
dc60: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
dc70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dc80: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
dc90: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
dca0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
dcb0: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
dcc0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
dcd0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
dce0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
dcf0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
dd00: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
dd10: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
dd20: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
dd30: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
dd40: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
dd50: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
dd60: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
dd70: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
dd80: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
dd90: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
dda0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ddb0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
ddc0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ddd0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
dde0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ddf0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
de00: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
de10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
de20: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
de30: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
de40: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
de50: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
de60: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
de70: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
de80: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
de90: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
dea0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
deb0: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
dec0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
ded0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
dee0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
def0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
df00: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
df10: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
df20: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
df30: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
df40: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
df50: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
df60: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
df70: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
df80: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
df90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
dfa0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
dfb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
dfc0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
dfd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dfe0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
dff0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e000: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e010: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e020: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e030: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e040: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e050: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
e060: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
e070: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
e080: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
e090: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
e0a0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
e0b0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
e0c0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
e0d0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
e0e0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
e0f0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
e100: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
e110: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
e120: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
e130: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
e140: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
e150: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
e160: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e170: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
e180: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
e190: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
e1a0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
e1b0: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
e1c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
e1d0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
e1e0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
e1f0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
e200: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
e210: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
e220: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
e230: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
e240: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
e250: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
e260: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
e270: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
e280: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
e290: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
e2a0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
e2b0: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
e2c0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
e2d0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
e2e0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
e2f0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e300: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e310: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
e320: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
e330: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
e340: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e350: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
e360: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
e370: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
e380: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
e390: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
e3a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e3b0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e3c0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
e3d0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e3e0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
e3f0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
e400: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
e410: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e420: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
e430: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
e440: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
e450: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
e460: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
e470: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e480: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
e490: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
e4a0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
e4b0: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
e4c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e4d0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
e4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e4f0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
e500: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
e510: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e520: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
e530: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
e540: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
e550: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
e560: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e570: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
e580: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e590: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e5a0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
e5b0: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
e5c0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
e5d0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
e5e0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
e5f0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
e600: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
e610: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
e620: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
e630: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
e640: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e650: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
e660: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
e670: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
e680: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
e690: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
e6a0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
e6b0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e6c0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
e6d0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
e6e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e6f0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
e700: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e710: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
e720: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
e730: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
e740: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
e750: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
e760: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e770: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
e780: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
e790: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
e7a0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
e7b0: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
e7c0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
e7d0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
e7e0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
e7f0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
e800: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
e810: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
e820: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
e830: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
e840: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
e850: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
e860: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
e870: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e880: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e890: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
e8a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
e8b0: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
e8c0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
e8d0: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
e8e0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
e8f0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
e900: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e910: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e920: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
e930: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
e940: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
e950: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e960: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
e970: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
e980: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
e990: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
e9a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
e9b0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
e9c0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
e9d0: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
e9e0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
e9f0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
ea00: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
ea10: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
ea20: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
ea30: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
ea40: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
ea50: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
ea60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
ea70: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
ea80: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
ea90: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
eaa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eab0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
eac0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
ead0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
eae0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
eaf0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
eb00: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
eb10: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
eb20: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
eb30: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
eb40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
eb50: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
eb60: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
eb70: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
eb80: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
eb90: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
eba0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
ebb0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
ebc0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
ebd0: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
ebe0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
ebf0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
ec00: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
ec10: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
ec20: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
ec30: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
ec40: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
ec50: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
ec60: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
ec70: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
ec80: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
ec90: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
eca0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
ecb0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
ecc0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
ecd0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
ece0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
ecf0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
ed00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
ed10: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
ed20: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
ed30: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
ed40: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
ed50: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
ed60: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
ed70: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
ed80: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
ed90: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
eda0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
edb0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
edc0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
edd0: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
ede0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
edf0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
ee00: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
ee10: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
ee20: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
ee30: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
ee40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ee50: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
ee60: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
ee70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
ee80: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
ee90: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
eea0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
eeb0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
eec0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
eed0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
eee0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
eef0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
ef00: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
ef10: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
ef20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ef30: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
ef40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef50: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
ef60: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
ef70: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
ef80: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
ef90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
efa0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
efb0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
efc0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
efd0: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
efe0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
eff0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f000: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f010: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f020: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f030: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f040: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f050: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
f060: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
f070: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
f080: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
f090: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0a0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
f0b0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
f0c0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
f0d0: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
f0e0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
f0f0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
f100: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f110: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
f120: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f130: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
f140: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
f150: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
f160: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
f170: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
f180: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
f190: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
f1a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f1b0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
f1c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
f1d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f1e0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
f1f0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f200: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
f210: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
f220: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
f230: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
f240: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
f250: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
f260: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
f270: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
f280: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
f290: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
f2a0: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
f2b0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f2c0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
f2d0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
f2e0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
f2f0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
f300: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
f310: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
f320: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
f330: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
f340: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
f350: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
f360: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
f370: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
f380: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
f390: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
f3a0: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
f3b0: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
f3c0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f3d0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
f3e0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
f3f0: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
f400: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
f410: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
f420: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
f430: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
f440: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
f450: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
f460: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
f470: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
f480: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
f490: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
f4a0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f4b0: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
f4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f4d0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
f4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f4f0: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
f500: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
f510: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
f520: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
f530: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
f540: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
f550: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
f560: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
f570: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
f580: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
f590: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
f5a0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
f5b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f5c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
f5d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
f5e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f5f0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
f600: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
f610: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
f620: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
f630: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
f640: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
f650: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
f660: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
f670: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
f680: 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
f690: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
f6a0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f6b0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
f6c0: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
f6d0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
f6e0: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
f6f0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
f700: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
f710: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
f720: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
f730: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
f740: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
f750: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
f760: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
f770: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
f780: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f790: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
f7a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f7b0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
f7c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f7d0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
f7e0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
f7f0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
f800: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
f810: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
f820: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
f830: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
f840: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
f850: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
f860: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f870: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
f880: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
f890: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
f8a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f8b0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
f8c0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f8d0: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
f8e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f8f0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
f900: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
f910: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
f920: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
f930: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
f940: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
f950: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
f960: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
f970: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
f980: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
f990: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
f9a0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
f9b0: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
f9c0: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
f9d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
f9e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
f9f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
fa00: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
fa10: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
fa20: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
fa30: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
fa40: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
fa50: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
fa60: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
fa70: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
fa80: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
fa90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
faa0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
fab0: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
fac0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
fad0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
fae0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
faf0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
fb00: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
fb10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fb20: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
fb30: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
fb40: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
fb50: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
fb60: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
fb70: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
fb80: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
fb90: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
fba0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
fbb0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
fbc0: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
fbd0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fbe0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
fbf0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
fc00: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
fc10: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
fc20: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
fc30: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
fc40: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
fc50: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
fc60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
fc70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
fc80: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
fc90: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
fca0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
fcb0: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
fcc0: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
fcd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fce0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
fcf0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
fd00: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
fd10: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
fd20: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
fd30: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
fd40: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
fd50: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
fd60: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
fd70: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
fd80: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
fd90: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
fda0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
fdb0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
fdc0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
fdd0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
fde0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
fdf0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
fe00: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
fe10: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
fe20: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
fe30: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
fe40: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
fe50: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
fe60: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
fe70: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
fe80: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
fe90: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
fea0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
feb0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
fec0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
fed0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
fee0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
fef0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
ff00: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
ff10: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
ff20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
ff30: 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
ff40: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
ff50: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
ff60: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
ff70: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
ff80: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
ff90: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
ffa0: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
ffb0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
ffc0: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
ffd0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
ffe0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
fff0: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
10000 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
10010 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
10020 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
10030 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
10040 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
10050 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10060 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10070 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10080 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10090 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
100a0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
100b0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
100c0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
100d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
100e0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
100f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10100 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10110 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10120 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10130 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10140 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10150 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10160 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10170 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10180 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10190 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
101a0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
101b0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
101c0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
101d0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
101e0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
101f0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10200 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10210 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10220 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10230 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10240 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10250 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10260 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10270 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10280 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10290 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
102a0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
102b0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
102c0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
102d0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
102e0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
102f0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10300 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10310 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
10320 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
10330 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
10340 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
10350 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
10360 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
10370 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
10380 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10390 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
103a0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
103b0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
103c0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
103d0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
103e0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
103f0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
10400 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
10410 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
10420 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
10430 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
10440 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
10450 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
10460 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
10470 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
10480 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
10490 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
104a0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
104b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
104c0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
104d0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
104e0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
104f0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
10500 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
10510 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
10520 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
10530 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
10540 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
10550 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
10560 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
10570 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
10580 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
10590 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
105a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
105b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
105c0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
105d0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
105e0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
105f0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
10600 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
10610 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
10620 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
10630 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
10640 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10650 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
10660 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
10670 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
10680 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10690 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
106a0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
106b0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
106c0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
106d0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
106e0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
106f0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
10700 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
10710 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
10720 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
10730 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
10740 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10750 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
10760 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
10770 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10780 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
10790 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
107a0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
107b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
107c0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
107d0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
107e0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
107f0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
10800 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
10810 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
10820 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
10830 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
10840 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
10850 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
10860 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
10870 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
10880 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
10890 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
108a0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
108b0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
108c0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
108d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
108e0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
108f0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10900 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
10910 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10920 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
10930 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
10940 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
10950 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
10960 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10970 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10980 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
10990 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
109a0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
109b0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
109c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
109d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
109e0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
109f0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
10a00 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
10a10 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
10a20 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
10a30 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
10a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
10a50 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
10a60 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
10a70 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10a80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10a90 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10aa0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10ab0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10ac0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10ad0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10ae0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10af0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10b00 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
10b10 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
10b20 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
10b30 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
10b40 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
10b50 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
10b60 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
10b70 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
10b80 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
10b90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
10ba0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10bb0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10bc0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10bd0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10be0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10bf0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10c00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
10c10 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
10c20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
10c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
10c40 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
10c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10c60 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
10c70 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10c80 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10c90 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10ca0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10cb0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10cc0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
10cd0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
10ce0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
10cf0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
10d00 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
10d10 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
10d20 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
10d30 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
10d40 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
10d50 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
10d60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10d70 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10d80 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10d90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10da0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10db0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10dc0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
10dd0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
10de0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10df0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
10e00 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
10e10 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
10e20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
10e30 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
10e40 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
10e50 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
10e60 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
10e70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
10e80 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
10e90 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
10ea0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10eb0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10ec0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
10ed0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10ee0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
10ef0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
10f00 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
10f10 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
10f20 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10f30 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10f40 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
10f50 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
10f60 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
10f70 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
10f80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10f90 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
10fa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
10fb0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
10fc0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
10fd0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
10fe0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
10ff0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11000 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11010 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11020 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
11030 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
11040 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
11050 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
11060 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
11070 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
11080 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11090 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
110a0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
110b0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
110c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
110d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
110e0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
110f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11100 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11110 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11120 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11130 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11140 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11150 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
11160 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
11170 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
11180 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11190 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
111a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
111b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
111c0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
111d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
111e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
111f0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
11200 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11210 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11220 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11230 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
11240 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11250 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11260 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11270 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11280 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11290 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
112a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
112b0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
112c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
112d0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
112e0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
112f0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
11300 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
11310 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
11320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
11330 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11340 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
11350 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
11360 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
11370 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
11380 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11390 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
113a0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
113b0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
113c0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
113d0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
113e0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
113f0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11410 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
11420 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
11430 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
11440 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
11450 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
11460 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
11470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11480 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
11490 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
114a0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
114b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
114c0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
114d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
114e0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
114f0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11500 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11510 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11520 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
11530 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
11540 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
11550 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
11560 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11570 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
11580 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11590 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
115a0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
115b0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
115c0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
115d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
115e0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
115f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11600 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
11610 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11620 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
11630 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
11640 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11650 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
11660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
11670 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11680 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11690 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
116a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
116b0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
116c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
116d0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
116e0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
116f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11700 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
11710 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
11720 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
11730 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
11740 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
11750 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
11760 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11770 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
11780 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
11790 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
117a0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
117b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
117c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
117d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
117e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
117f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11800 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11810 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11820 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11830 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
11840 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
11850 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11860 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11870 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11880 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
11890 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
118a0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
118b0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
118c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
118d0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
118e0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
118f0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11900 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
11910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
11920 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
11930 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
11940 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
11950 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
11960 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
11970 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
11980 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
11990 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
119a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
119b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
119c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
119d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
119e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
119f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
11a00 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
11a10 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
11a20 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
11a30 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
11a40 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
11a50 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
11a60 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
11a70 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
11a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a90 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11aa0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
11ab0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
11ac0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
11ad0 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
11ae0 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
11af0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11b00 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
11b10 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11b20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
11b30 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
11b40 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
11b50 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
11b60 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11b70 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
11b80 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
11b90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11ba0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11bb0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
11bc0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
11bd0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
11be0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
11bf0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
11c00 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
11c10 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11c20 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11c30 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
11c40 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
11c50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11c60 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11c70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c80 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
11c90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11ca0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
11cb0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
11cc0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
11cd0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
11ce0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
11cf0 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
11d00 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
11d10 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
11d20 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
11d30 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
11d40 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
11d50 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
11d60 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
11d70 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
11d80 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
11d90 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
11da0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
11db0 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
11dc0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
11dd0 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
11de0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
11df0 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
11e00 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
11e10 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
11e20 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
11e30 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
11e40 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
11e50 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
11e60 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11e70 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
11e80 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
11e90 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
11ea0 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
11eb0 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
11ec0 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
11ed0 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
11ee0 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
11ef0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11f00 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
11f10 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
11f20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
11f30 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
11f40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
11f50 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
11f60 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
11f70 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
11f80 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
11f90 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
11fa0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
11fb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
11fc0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
11fd0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
11fe0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
11ff0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12000 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12010 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12020 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
12030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12040 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
12050 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12060 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12070 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12080 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12090 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
120a0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
120b0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
120c0 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
120d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
120e0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
120f0 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12100 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12110 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12120 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
12130 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12140 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
12150 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
12160 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
12170 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
12180 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12190 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
121a0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
121b0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
121c0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
121d0 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
121e0 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
121f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12200 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12210 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12220 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
12230 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
12240 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
12250 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
12260 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
12270 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
12280 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12290 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
122a0 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
122b0 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
122c0 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
122d0 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
122e0 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
122f0 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12300 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12310 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12320 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
12330 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
12340 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
12350 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
12360 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
12370 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
12380 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12390 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
123a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
123b0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
123c0 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
123d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
123e0 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
123f0 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12400 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12410 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12420 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
12430 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
12440 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
12450 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
12460 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12470 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
12480 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
124a0 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
124b0 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
124c0 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
124d0 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
124e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
124f0 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12500 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12510 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12520 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
12530 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
12540 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
12550 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12560 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
12570 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12580 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
12590 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
125a0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
125b0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
125c0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
125d0 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
125e0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
125f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12600 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
12610 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
12620 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
12630 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
12640 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
12650 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
12660 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
12670 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
12680 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
12690 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
126a0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
126b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
126c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
126d0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
126e0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
126f0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
12700 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
12710 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12720 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
12730 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
12740 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
12750 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12760 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
12770 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
12780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
12790 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
127a0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
127b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
127c0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
127d0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
127e0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
127f0 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
12800 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
12810 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
12820 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
12830 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
12840 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
12850 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
12860 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
12870 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
12880 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
12890 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
128a0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
128b0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
128c0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
128d0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
128e0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
128f0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12900 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
12910 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
12920 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
12930 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
12940 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
12950 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
12960 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
12970 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
12980 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12990 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
129a0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
129b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
129c0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
129d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
129e0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
129f0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12a00 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12a10 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12a20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12a30 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12a40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12a50 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12a60 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
12a70 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12a80 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12a90 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
12aa0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12ab0 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
12ac0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
12ad0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12ae0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
12af0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12b00 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
12b10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12b20 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
12b30 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
12b40 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
12b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12b60 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
12b70 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12b80 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12b90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12ba0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12bb0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12bc0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12bd0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12be0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12bf0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12c00 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
12c10 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
12c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12c30 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
12c40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12c50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12c60 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
12c70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12c80 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
12c90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12ca0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
12cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12cc0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12cd0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12ce0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12cf0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12d00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12d10 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12d20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12d30 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12d40 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
12d50 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
12d60 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12d70 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12d80 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12d90 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
12da0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12db0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12dc0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12dd0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12de0 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
12df0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
12e00 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
12e10 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
12e20 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
12e30 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
12e40 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
12e50 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
12e60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12e70 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12e80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12e90 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12ea0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12eb0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12ec0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
12ed0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
12ee0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
12ef0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
12f00 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
12f10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12f20 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
12f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12f40 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
12f50 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
12f60 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
12f70 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
12f80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12f90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
12fa0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12fb0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
12fc0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12fd0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
12fe0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
12ff0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13000 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13010 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13020 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
13030 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13040 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
13050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13060 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
13070 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
13080 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13090 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
130a0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
130b0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
130c0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
130d0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
130e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
130f0 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13100 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13110 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13120 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
13130 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
13140 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
13150 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
13160 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13170 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
13180 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13190 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
131a0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
131b0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
131c0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
131d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
131e0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
131f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13200 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13210 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13220 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13230 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13240 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
13250 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13260 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13270 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
13280 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13290 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
132a0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
132b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
132c0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
132d0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
132e0 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
132f0 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13300 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13310 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13320 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13330 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
13340 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13350 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
13360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13370 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13380 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13390 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
133a0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
133b0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
133c0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
133d0 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
133e0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
133f0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13400 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13410 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13420 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13430 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
13440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13450 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
13460 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
13470 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
13480 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
13490 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
134a0 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
134b0 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
134c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
134d0 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
134e0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
134f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
13500 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
13510 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
13520 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
13530 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
13540 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
13550 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
13560 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
13570 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
13580 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
13590 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
135a0 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
135b0 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
135c0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
135d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
135e0 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
135f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13600 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
13610 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
13620 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
13630 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
13640 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
13650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13660 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
13670 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
13680 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
13690 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
136a0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
136b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
136c0 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
136d0 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
136e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
136f0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
13700 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
13710 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
13720 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13730 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
13740 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
13750 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
13760 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
13770 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
13780 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
13790 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
137a0 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
137b0 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
137c0 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
137d0 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
137e0 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
137f0 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
13800 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
13810 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
13820 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
13830 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
13840 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
13850 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
13860 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
13870 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
13880 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
13890 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
138a0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
138b0 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
138c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
138d0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
138e0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
138f0 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
13900 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13910 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
13920 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
13930 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20  RI.** <dd> This 
13940 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13950 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
13960 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e  f type int. If n
13970 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a  on-zero, then.**
13980 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
13990 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
139a0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
139b0 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ter is zero, the
139c0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a  n URI handling.*
139d0 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  * is globally di
139e0 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68  sabled. If URI h
139f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
13a00 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c  lly enabled, all
13a10 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61   filenames.** pa
13a20 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
13a30 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
13a40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b  e3_open_v2()], [
13a50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
13a60 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65  ] or.** specifie
13a70 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54  d as part of [AT
13a80 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61  TACH] commands a
13a90 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
13aa0 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65  s URIs, regardle
13ab0 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72  ss.** of whether
13ac0 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
13ad0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
13ae0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
13af0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
13b00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
13b10 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c  ned. If it is gl
13b20 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
13b30 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
13b40 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
13b50 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
13b60 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
13b70 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
13b80 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
13b90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
13ba0 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61   opened. By defa
13bb0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
13bc0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
13bd0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
13be0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
13bf0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
13c00 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
13c10 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
13c20 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
13c30 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ined..**.** [[SQ
13c40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
13c50 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
13c60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13c70 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
13c80 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20  EX_SCAN.** <dd> 
13c90 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13ca0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
13cb0 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  er argument whic
13cc0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
13cd0 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e   as.** a boolean
13ce0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
13cf0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
13d00 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
13d10 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a  ng indices for.*
13d20 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  * full table sca
13d30 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
13d40 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20  optimizer.  The 
13d50 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
13d60 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
13d70 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
13d80 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
13d90 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
13da0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
13db0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
13dc0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
13dd0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
13de0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
13df0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
13e00 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
13e10 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
13e20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
13e30 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
13e40 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
13e50 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
13e60 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
13e70 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  malfunction.** m
13e80 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20  alfunction when 
13e90 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
13ea0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
13eb0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
13ec0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
13ed0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
13ee0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
13ef0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
13f00 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
13f10 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
13f20 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
13f30 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
13f40 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
13f50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13f60 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
13f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13f80 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
13f90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13fa0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
13fb0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
13fc0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
13fd0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
13fe0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
13ff0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
14000 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
14010 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
14020 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
14030 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
14040 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
14050 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14060 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
14070 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14080 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
14090 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
140a0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
140b0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
140c0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
140d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
140e0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
140f0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
14100 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
14110 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
14120 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
14130 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
14140 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
14150 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
14160 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
14170 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
14180 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
14190 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
141a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
141b0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
141c0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
141d0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
141e0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
141f0 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
14200 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
14210 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
14220 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
14230 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
14240 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14250 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
14260 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
14270 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
14280 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
14290 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
142a0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
142b0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
142c0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
142d0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
142e0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
142f0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
14300 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
14310 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14320 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
14330 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
14340 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
14350 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
14360 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
14370 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14380 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
14390 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
143a0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
143b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
143c0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
143d0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
143e0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
143f0 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
14400 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
14410 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
14420 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14430 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
14440 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
14450 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
14460 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
14470 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
14480 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
14490 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
144a0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
144b0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
144c0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
144d0 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49 54 45  ZE.** <dd>SQLITE
144e0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
144f0 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
14500 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
14510 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
14520 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
14530 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
14540 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
14550 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
14560 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
14570 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
14580 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14590 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
145a0 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  t..** The defaul
145b0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
145c0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
145d0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
145e0 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
145f0 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
14600 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
14610 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
14620 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
14630 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
14640 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
14650 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 61  .  The maximum a
14660 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
14670 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  .** cannot be ch
14680 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  anged at run-tim
14690 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20  e.  Nor may the 
146a0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
146b0 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63  mmap size.** exc
146c0 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  eed the compile-
146d0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
146e0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
146f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
14700 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
14710 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
14720 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65 72 20    .** If either 
14730 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
14740 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74   option is negat
14750 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61  ive, then that a
14760 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68  rgument is.** ch
14770 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d  anged to its com
14780 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c  pile-time defaul
14790 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  t..** </dl>.*/.#
147a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
147b0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
147c0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
147d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
147e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
147f0 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
14800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14810 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14820 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
14830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14840 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
14850 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
14860 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
14870 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14880 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
14890 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
148a0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
148b0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
148c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
148d0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
148e0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
148f0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
14900 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14910 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
14920 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
14930 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14940 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14950 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
14960 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
14970 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
14980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14990 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
149a0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
149b0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
149c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
149d0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
149e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
149f0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
14a00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14a10 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
14a20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
14a30 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
14a40 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
14a50 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
14a60 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
14a70 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
14a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14a90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14aa0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
14ab0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
14ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14ad0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
14ae0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
14af0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14b00 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
14b10 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
14b20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14b30 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
14b40 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
14b50 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
14b60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
14b70 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
14b80 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
14b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14ba0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
14bb0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
14bc0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
14bd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14be0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
14bf0 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
14c00 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
14c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14c20 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
14c30 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
14c40 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
14c50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14c60 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
14c70 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
14c80 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
14c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14ca0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
14cb0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
14cc0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
14cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14ce0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
14cf0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
14d00 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
14d10 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
14d20 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
14d30 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
14d40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14d50 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
14d60 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
14d70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14d80 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
14d90 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
14da0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
14db0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14dc0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
14dd0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
14de0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
14df0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
14e00 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14e10 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
14e20 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
14e30 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
14e40 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
14e50 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
14e60 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14e70 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
14e80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
14e90 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
14ea0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14eb0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
14ec0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
14ed0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
14ee0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
14ef0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
14f00 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
14f10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
14f20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
14f30 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
14f40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14f50 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14f60 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
14f70 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
14f80 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
14f90 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
14fa0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
14fb0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
14fc0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
14fd0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
14fe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14ff0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
15000 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
15010 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15020 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
15030 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
15040 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
15050 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
15060 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
15070 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
15080 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15090 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
150a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
150b0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
150c0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
150d0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
150e0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
150f0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
15100 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
15110 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15120 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
15130 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
15140 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
15150 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
15160 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
15170 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
15180 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15190 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
151a0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
151b0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
151c0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
151d0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
151e0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
151f0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
15200 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
15210 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
15220 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
15230 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15240 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
15250 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
15260 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
15270 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15280 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
15290 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
152a0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
152b0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
152c0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
152d0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
152e0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
152f0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
15300 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15310 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
15320 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
15330 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
15340 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
15350 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
15360 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
15370 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
15380 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
15390 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
153a0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
153b0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
153c0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
153d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
153e0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
153f0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
15400 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
15410 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
15420 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
15430 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
15440 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
15450 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
15460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
15470 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
15480 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
15490 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
154a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
154b0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
154c0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
154d0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
154e0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
154f0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
15500 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
15510 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
15520 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
15530 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
15540 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
15550 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
15560 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
15570 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
15580 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
15590 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
155a0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
155b0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
155c0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
155d0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
155e0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
155f0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
15600 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
15610 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15620 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
15630 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
15640 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
15650 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
15660 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
15670 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
15680 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
15690 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
156a0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
156b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
156c0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
156d0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
156e0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
156f0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
15700 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
15710 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15720 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
15730 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
15740 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
15750 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
15760 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
15770 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
15780 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
15790 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
157a0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
157b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
157c0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
157d0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
157e0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
157f0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
15800 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
15810 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
15820 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
15830 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
15840 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
15850 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
15860 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
15870 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
15880 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
15890 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
158a0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
158b0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
158c0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
158d0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
158e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
158f0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
15900 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
15910 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
15920 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
15930 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
15940 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
15950 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
15960 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
15970 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
15980 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
15990 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
159a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
159b0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
159c0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
159d0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
159e0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
159f0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
15a00 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
15a10 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
15a20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
15a30 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
15a40 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
15a50 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
15a60 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
15a70 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
15a80 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
15a90 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
15aa0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
15ab0 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
15ac0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
15ad0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
15ae0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
15af0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
15b00 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
15b10 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
15b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
15b30 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
15b40 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
15b50 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
15b60 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
15b70 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
15b80 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
15b90 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
15ba0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
15bb0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
15bc0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
15bd0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
15be0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
15bf0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
15c00 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
15c10 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
15c20 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
15c30 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
15c40 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
15c50 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
15c60 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
15c70 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
15c80 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
15c90 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
15ca0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
15cb0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
15cc0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
15cd0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
15ce0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
15cf0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
15d00 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
15d10 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
15d20 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
15d30 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
15d40 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
15d50 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
15d60 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
15d70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
15d80 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
15d90 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
15da0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
15db0 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
15dc0 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
15dd0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
15de0 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
15df0 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
15e00 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
15e10 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
15e20 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
15e30 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
15e40 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
15e50 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
15e60 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
15e70 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
15e80 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
15e90 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
15ea0 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
15eb0 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
15ec0 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
15ed0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
15ee0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
15ef0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
15f00 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
15f10 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
15f20 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
15f30 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
15f40 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
15f50 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
15f60 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
15f70 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
15f80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
15f90 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
15fa0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
15fb0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
15fc0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
15fd0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
15fe0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
15ff0 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
16000 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
16010 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
16020 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
16030 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
16040 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
16050 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
16060 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
16070 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
16080 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
16090 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
160a0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
160b0 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
160c0 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
160d0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
160e0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
160f0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
16100 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
16110 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
16120 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
16130 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
16140 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
16150 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
16160 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
16170 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
16180 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
16190 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
161a0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
161b0 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
161c0 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
161d0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
161e0 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
161f0 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
16200 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
16210 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
16220 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
16230 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
16240 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
16250 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
16260 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
16270 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
16280 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
16290 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
162a0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
162b0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
162c0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
162d0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
162e0 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
162f0 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
16300 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
16310 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
16320 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
16330 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
16340 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
16350 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
16360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16370 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
16380 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
16390 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
163a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
163b0 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
163c0 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
163d0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
163e0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
163f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
16400 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
16410 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
16420 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
16430 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
16440 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
16450 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
16460 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
16470 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
16480 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16490 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
164a0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
164b0 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
164c0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
164d0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
164e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
164f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
16500 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
16510 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
16520 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
16530 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
16540 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
16550 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
16560 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
16570 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
16580 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
16590 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
165a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
165b0 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68  (Only changes th
165c0 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
165d0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
165e0 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
165f0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45  TE],.** or [DELE
16600 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72  TE] statement ar
16610 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
16620 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
16630 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
16640 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20  ers or [foreign 
16650 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
16660 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20   not counted.)^ 
16670 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Use the.** [sqli
16680 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
16690 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f  s()] function to
166a0 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
166b0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
166c0 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63  s.** including c
166d0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
166e0 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f   triggers and fo
166f0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
16700 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65  s..**.** ^Change
16710 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
16720 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62   are simulated b
16730 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  y an [INSTEAD OF
16740 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65   trigger].** are
16750 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f   not counted.  O
16760 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63  nly real table c
16770 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
16780 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72  ed..**.** ^(A "r
16790 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
167a0 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
167b0 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
167c0 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
167d0 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
167e0 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
167f0 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
16800 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
16810 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
16820 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c  effects of [REPL
16830 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
16840 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
16850 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
16860 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50  rocessing, [DROP
16870 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61   TABLE], or by a
16880 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
16890 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
168a0 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
168b0 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a  w changes.)^.**.
168c0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
168d0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
168e0 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
168f0 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
16900 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
16910 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45  script of a [CRE
16920 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
16930 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74  igger]. .** Most
16940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16950 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
16960 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
16970 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
16980 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
16990 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
169a0 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
169b0 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
169c0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
169d0 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
169e0 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
169f0 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
16a00 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
16a10 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
16a20 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
16a30 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
16a40 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
16a50 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73  *.** ^Calling [s
16a60 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
16a70 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
16a80 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
16a90 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
16aa0 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
16ab0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
16ac0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
16ad0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16ae0 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
16af0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
16b00 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
16b10 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
16b20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
16b30 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
16b40 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
16b50 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73  ext..**.** ^Thus
16b60 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
16b70 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
16b80 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
16b90 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
16ba0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
16bb0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
16bc0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
16bd0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
16be0 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
16bf0 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
16c00 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20  evel.  ^(Within 
16c10 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
16c20 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
16c30 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
16c40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
16c50 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
16c60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
16c70 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
16c80 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
16c90 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
16ca0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
16cb0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
16cc0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
16cd0 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
16ce0 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
16cf0 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
16d00 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
16d10 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
16d20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
16d30 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
16d40 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
16d50 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a   context.)^.**.*
16d60 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
16d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
16d80 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
16d90 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
16da0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
16db0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
16dc0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
16dd0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
16de0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
16df0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
16e00 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
16e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
16e20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
16e30 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
16e40 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
16e50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
16e60 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
16e70 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
16e80 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
16e90 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
16ea0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
16eb0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
16ec0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
16ed0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
16ee0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
16ef0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16f00 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
16f10 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
16f20 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
16f30 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
16f40 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
16f50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16f60 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
16f70 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
16f80 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
16f90 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
16fa0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
16fb0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
16fc0 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
16fd0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
16fe0 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
16ff0 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
17000 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
17010 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
17020 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
17030 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
17040 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
17050 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
17060 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
17070 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
17080 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
17090 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
170a0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
170b0 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
170c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
170d0 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
170e0 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
170f0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
17100 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
17110 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
17120 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
17130 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
17140 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
17150 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
17160 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
17170 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
17180 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
17190 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
171a0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
171b0 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
171c0 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
171d0 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
171e0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
171f0 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
17200 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
17210 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
17220 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
17230 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
17240 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17250 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
17260 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
17270 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
17280 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
17290 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
172a0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
172b0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
172c0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
172d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
172e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
172f0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
17300 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
17310 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
17320 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
17330 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
17340 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
17350 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
17360 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
17370 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
17380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17390 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
173a0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
173b0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
173c0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
173d0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
173e0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
173f0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
17400 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
17410 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
17420 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
17430 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
17440 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
17450 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
17460 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
17470 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
17480 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
17490 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
174a0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
174b0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
174c0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
174d0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
174e0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
174f0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
17500 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
17510 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
17520 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
17530 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
17540 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
17550 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
17560 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
17570 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
17580 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
17590 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
175a0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
175b0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
175c0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
175d0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
175e0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
175f0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
17600 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
17610 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
17620 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
17630 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
17640 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
17650 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
17660 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
17670 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
17680 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
17690 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
176a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
176b0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
176c0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
176d0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
176e0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
176f0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
17700 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
17710 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
17720 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17730 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
17740 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
17750 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
17760 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
17770 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
17780 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
17790 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
177a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
177b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
177c0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
177d0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
177e0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
177f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
17800 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
17810 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
17820 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
17830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
17840 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
17850 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
17860 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17870 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
17880 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
17890 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
178a0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
178b0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
178c0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
178d0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
178e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
178f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
17900 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
17910 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
17920 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
17930 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
17940 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
17950 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
17960 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
17970 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17980 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
17990 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
179a0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
179b0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
179c0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
179d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
179e0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
179f0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
17a00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
17a10 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
17a20 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
17a30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17a40 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
17a50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
17a60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17a70 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
17a80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17a90 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
17aa0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
17ab0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
17ac0 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
17ad0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17ae0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
17af0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
17b00 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
17b10 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
17b20 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
17b30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
17b40 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
17b50 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
17b60 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
17b70 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
17b80 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
17b90 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
17ba0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
17bb0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
17bc0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
17bd0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
17be0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
17bf0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
17c00 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
17c10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
17c20 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
17c30 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
17c40 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
17c50 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
17c60 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
17c70 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
17c80 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
17c90 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
17ca0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
17cb0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
17cc0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
17cd0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
17ce0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
17cf0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
17d00 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
17d10 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
17d20 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
17d30 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
17d40 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
17d50 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
17d60 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
17d70 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
17d80 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
17d90 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
17da0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
17db0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
17dc0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
17dd0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
17de0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
17df0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
17e00 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
17e10 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
17e20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
17e30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
17e40 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
17e50 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
17e60 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
17e70 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
17e80 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
17e90 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
17ea0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
17eb0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
17ec0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
17ed0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17ee0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
17ef0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
17f00 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
17f10 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
17f20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
17f30 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
17f40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
17f50 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
17f60 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
17f70 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
17f80 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
17f90 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
17fa0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
17fb0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
17fc0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
17fd0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
17fe0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
17ff0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
18000 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
18010 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
18020 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
18030 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
18040 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
18050 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
18060 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
18070 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
18080 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18090 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
180a0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
180b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
180c0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
180d0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
180e0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
180f0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
18100 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
18110 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
18120 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
18130 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
18140 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
18150 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
18160 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
18170 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
18180 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
18190 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
181a0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
181b0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
181c0 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
181d0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
181e0 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
181f0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
18200 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
18210 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
18220 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
18230 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
18240 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
18250 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
18260 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
18270 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
18280 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18290 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
182a0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
182b0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
182c0 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
182d0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
182e0 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
182f0 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
18300 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
18310 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
18320 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
18330 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
18340 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
18350 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
18360 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
18370 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
18380 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
18390 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
183a0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
183b0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
183c0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
183d0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
183e0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
183f0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
18400 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
18410 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
18420 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
18430 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
18440 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
18450 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
18460 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
18470 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
18480 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18490 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
184a0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
184b0 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
184c0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
184d0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
184e0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
184f0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
18500 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
18510 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
18520 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
18530 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
18540 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
18550 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
18560 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
18570 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
18580 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
18590 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
185a0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
185b0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
185c0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
185d0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
185e0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
185f0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
18600 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
18610 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
18620 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
18630 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
18640 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
18650 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
18660 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
18670 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
18680 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
18690 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
186a0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
186b0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
186c0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
186d0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
186e0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
186f0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
18700 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
18710 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
18720 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
18730 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
18740 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
18750 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
18760 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
18770 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
18780 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
18790 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
187a0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
187b0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
187c0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
187d0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
187e0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
187f0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
18800 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
18810 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
18820 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
18830 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
18840 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
18850 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
18860 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
18870 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
18880 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
18890 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
188a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
188b0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
188c0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
188d0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
188e0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
188f0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
18900 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
18910 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
18920 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
18930 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
18940 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
18950 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
18960 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
18970 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
18980 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
18990 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
189a0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
189b0 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
189c0 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
189d0 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
189e0 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
189f0 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
18a00 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
18a10 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
18a20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
18a30 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
18a40 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
18a50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
18a60 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
18a70 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
18a80 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
18a90 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
18aa0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
18ab0 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
18ac0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
18ad0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
18ae0 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
18af0 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
18b00 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
18b10 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
18b20 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
18b30 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
18b40 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
18b50 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
18b60 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
18b70 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
18b80 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
18b90 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
18ba0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
18bb0 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
18bc0 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
18bd0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
18be0 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
18bf0 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
18c00 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
18c10 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
18c20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
18c30 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
18c40 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
18c50 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
18c60 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
18c70 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
18c80 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
18c90 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
18ca0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
18cb0 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
18cc0 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
18cd0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
18ce0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
18cf0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
18d00 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
18d10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18d20 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
18d30 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
18d40 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
18d50 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
18d60 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
18d70 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
18d80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
18d90 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
18da0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
18db0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
18dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
18dd0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
18de0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
18df0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
18e00 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
18e10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
18e20 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
18e30 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
18e40 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
18e50 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
18e60 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
18e70 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
18e80 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
18e90 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
18ea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
18eb0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
18ec0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
18ed0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
18ee0 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
18ef0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
18f00 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
18f10 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
18f20 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
18f30 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
18f40 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
18f50 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
18f60 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
18f70 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
18f80 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
18f90 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
18fa0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
18fb0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
18fc0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
18fd0 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
18fe0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
18ff0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
19000 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
19010 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
19020 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
19030 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
19040 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
19050 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
19060 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
19070 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
19080 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
19090 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
190a0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
190b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
190c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
190d0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
190e0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
190f0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
19100 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
19110 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
19120 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
19130 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
19140 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
19150 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
19160 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
19170 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
19180 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
191a0 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
191b0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
191c0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
191d0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
191e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
191f0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
19200 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
19210 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
19220 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
19230 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
19240 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ed.)^.*/.int sql
19250 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
19260 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
19270 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
19280 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
19290 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
192a0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
192b0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
192c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
192d0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
192e0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
192f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
19300 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
19310 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
19320 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
19330 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
19340 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
19350 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
19360 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
19370 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
19380 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19390 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
193a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
193b0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
193c0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
193d0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
193e0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
193f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
19400 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
19410 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
19420 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
19430 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
19440 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
19450 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
19460 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
19470 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
19480 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
19490 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
194a0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
194b0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
194c0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
194d0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
194e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
194f0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
19500 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
19510 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
19520 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
19530 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
19540 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
19550 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
19560 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
19570 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
19580 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
19590 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
195a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
195b0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
195c0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
195d0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
195e0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
195f0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
19600 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
19610 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
19620 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
19630 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
19640 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
19650 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
19660 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
19670 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
19680 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
19690 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
196a0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
196b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
196c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
196d0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
196e0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
196f0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
19700 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
19710 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
19720 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
19730 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
19740 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
19750 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
19760 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
19770 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
19780 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
19790 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
197a0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
197b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
197c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
197d0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
197e0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
197f0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
19800 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
19810 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
19820 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
19830 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
19840 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
19850 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
19860 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
19870 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
19880 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
19890 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
198a0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
198b0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
198c0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
198d0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
198e0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
198f0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
19900 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
19910 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
19920 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
19930 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
19940 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19950 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
19960 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
19970 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
19980 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19990 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
199a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
199b0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
199c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
199d0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
199e0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
199f0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
19a00 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
19a10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
19a20 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
19a30 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19a40 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
19a50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19a60 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
19a70 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19a80 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
19a90 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
19aa0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
19ab0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
19ac0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
19ad0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
19ae0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
19af0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
19b00 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
19b10 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
19b20 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
19b30 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
19b40 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
19b50 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
19b60 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
19b70 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
19b80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
19b90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
19ba0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
19bb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19bc0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
19bd0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
19be0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
19bf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
19c00 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
19c10 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
19c20 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
19c30 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
19c40 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
19c50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
19c60 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
19c70 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
19c80 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
19c90 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
19ca0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
19cb0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
19cc0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
19cd0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
19ce0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
19cf0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
19d00 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
19d10 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
19d20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
19d30 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
19d40 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
19d50 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
19d60 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
19d70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
19d80 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
19d90 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19da0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
19db0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
19dc0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
19dd0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
19de0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
19df0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
19e00 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
19e10 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
19e20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
19e30 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
19e40 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
19e50 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
19e60 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
19e70 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
19e80 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
19e90 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
19ea0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
19eb0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
19ec0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
19ed0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
19ee0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
19ef0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
19f00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
19f10 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
19f20 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
19f30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
19f40 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
19f50 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
19f60 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
19f70 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
19f80 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
19f90 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
19fa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
19fb0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
19fc0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
19fd0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
19fe0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
19ff0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1a000 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1a010 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1a020 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1a030 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1a040 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1a050 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1a060 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1a070 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1a080 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1a090 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1a0a0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1a0b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1a0c0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1a0d0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1a0e0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1a0f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1a100 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1a110 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
1a120 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1a130 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1a140 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1a150 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1a160 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1a170 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1a180 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1a190 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1a1a0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1a1b0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1a1c0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1a1d0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1a1e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a1f0 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1a200 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1a210 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1a220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a230 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1a240 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1a250 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1a260 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1a270 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1a280 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1a290 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1a2a0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1a2b0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1a2c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1a2d0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1a2e0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1a2f0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1a300 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1a310 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a320 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1a330 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1a340 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1a350 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1a360 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1a370 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1a380 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1a390 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1a3a0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1a3b0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1a3c0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1a3d0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1a3e0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1a3f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1a400 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1a410 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1a420 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1a430 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1a440 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1a450 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1a460 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1a470 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1a480 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1a490 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1a4a0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1a4b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1a4c0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1a4d0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1a4e0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1a4f0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1a500 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1a510 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1a520 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1a530 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1a540 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1a550 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1a560 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1a570 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1a580 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1a590 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1a5a0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1a5b0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1a5c0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1a5d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1a5e0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1a5f0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1a600 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1a610 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1a620 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1a630 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1a640 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1a650 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1a660 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1a670 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1a680 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1a690 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1a6a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1a6b0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1a6c0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1a6d0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1a6e0 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1a6f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1a700 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1a710 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1a720 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1a730 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1a740 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1a750 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1a760 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1a770 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1a780 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1a790 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1a7a0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1a7b0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1a7c0 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
1a7d0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1a7e0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1a7f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1a800 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1a810 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1a820 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1a830 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1a840 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1a850 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1a860 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1a870 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1a880 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1a890 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1a8a0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1a8b0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1a8c0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1a8d0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1a8e0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1a8f0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1a900 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1a910 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1a920 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1a930 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1a940 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1a950 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1a960 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1a970 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a980 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1a990 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1a9a0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1a9b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a9c0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1a9d0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1a9e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1a9f0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1aa00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1aa10 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1aa20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1aa30 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1aa40 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1aa50 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1aa60 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1aa70 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1aa80 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1aa90 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1aaa0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1aab0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1aac0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1aad0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1aae0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1aaf0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1ab00 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1ab10 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1ab20 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1ab30 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1ab40 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1ab50 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1ab60 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1ab70 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1ab80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ab90 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1aba0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1abb0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1abc0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1abd0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1abe0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1abf0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1ac00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ac10 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1ac20 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1ac30 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1ac40 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ac50 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1ac60 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1ac70 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1ac80 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1ac90 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1aca0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1acb0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1acc0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1acd0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1ace0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1acf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1ad00 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1ad10 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1ad20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1ad30 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1ad40 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1ad50 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1ad60 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1ad70 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1ad80 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1ad90 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1ada0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1adb0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1adc0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1add0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1ade0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1adf0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1ae00 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1ae10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ae20 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1ae30 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1ae40 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1ae50 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1ae60 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1ae70 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1ae80 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ae90 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1aea0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1aeb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1aec0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1aed0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1aee0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1aef0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1af00 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1af10 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1af20 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1af30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1af40 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1af50 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1af60 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1af70 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1af80 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1af90 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1afa0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1afb0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1afc0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1afd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1afe0 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1aff0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1b000 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1b010 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1b020 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1b030 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1b040 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1b050 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1b060 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b070 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1b080 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1b090 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1b0a0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1b0b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1b0c0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1b0d0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1b0e0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1b0f0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1b100 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1b110 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1b120 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1b130 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1b140 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1b150 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1b160 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1b170 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1b180 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1b190 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1b1a0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1b1b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1b1c0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1b1d0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1b1e0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1b1f0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1b200 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1b210 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1b220 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1b230 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1b240 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1b250 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1b260 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1b270 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1b280 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1b290 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1b2a0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1b2b0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1b2c0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1b2d0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1b2e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1b2f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1b300 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1b310 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1b320 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1b330 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1b340 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1b350 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1b360 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1b370 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1b380 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1b390 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1b3a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1b3b0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1b3c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1b3d0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1b3e0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1b3f0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1b400 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1b410 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1b420 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1b430 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1b440 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1b450 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1b460 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1b470 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1b480 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1b490 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1b4a0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1b4b0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1b4c0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1b4d0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1b4e0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1b4f0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1b500 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1b510 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1b520 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1b530 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1b540 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1b550 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1b560 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1b570 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1b580 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1b590 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1b5a0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1b5b0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1b5c0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1b5d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1b5e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1b5f0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
1b600 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1b610 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
1b620 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1b630 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1b640 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b650 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1b660 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
1b670 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
1b680 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1b690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b6a0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
1b6b0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1b6c0 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
1b6d0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
1b6e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b6f0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1b700 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b710 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1b720 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1b730 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1b740 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1b750 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1b760 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1b770 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1b780 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
1b790 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b7a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1b7b0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1b7c0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1b7d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1b7e0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1b7f0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1b800 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
1b810 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
1b820 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1b830 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1b840 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
1b850 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1b860 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1b870 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1b880 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1b890 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1b8a0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1b8b0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1b8c0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
1b8d0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1b8e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1b8f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1b900 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1b910 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1b920 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1b930 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1b940 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1b950 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1b960 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1b970 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
1b980 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b990 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1b9a0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1b9b0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
1b9c0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
1b9d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
1b9e0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1b9f0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1ba00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1ba10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
1ba20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ba30 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
1ba40 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
1ba50 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
1ba60 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
1ba70 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
1ba80 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
1ba90 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
1baa0 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
1bab0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
1bac0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
1bad0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1bae0 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
1baf0 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
1bb00 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
1bb10 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
1bb20 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
1bb30 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
1bb40 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
1bb50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1bb60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1bb70 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
1bb80 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
1bb90 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
1bba0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
1bbb0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
1bbc0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
1bbd0 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
1bbe0 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
1bbf0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
1bc00 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
1bc10 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
1bc20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
1bc30 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
1bc40 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
1bc50 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
1bc60 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
1bc70 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
1bc80 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
1bc90 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
1bca0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
1bcb0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
1bcc0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
1bcd0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
1bce0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
1bcf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1bd00 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
1bd10 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1bd20 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
1bd30 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1bd40 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1bd50 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1bd60 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1bd70 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1bd80 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1bd90 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1bda0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1bdb0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1bdc0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1bdd0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1bde0 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1bdf0 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1be00 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1be10 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1be20 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1be30 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1be40 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1be50 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1be60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1be70 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1be80 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1be90 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1bea0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1beb0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1bec0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1bed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1bee0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1bef0 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
1bf00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1bf10 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
1bf20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bf30 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1bf40 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1bf50 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1bf60 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1bf70 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1bf80 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1bf90 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1bfa0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1bfb0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1bfc0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1bfd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1bfe0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1bff0 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1c000 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c010 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1c020 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1c030 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1c040 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1c050 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1c060 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c070 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1c080 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1c090 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1c0a0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1c0b0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1c0c0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1c0d0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1c0e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c0f0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1c100 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1c110 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1c120 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1c130 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1c140 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1c150 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1c160 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1c170 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1c180 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1c190 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1c1a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1c1b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1c1c0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1c1d0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1c1e0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1c1f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c200 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1c210 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1c220 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1c230 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1c240 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1c250 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1c260 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1c270 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1c280 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1c290 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1c2a0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1c2b0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1c2c0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1c2d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c2e0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1c2f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1c300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1c310 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1c320 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1c330 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1c340 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1c350 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1c360 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1c370 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1c380 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1c390 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1c3a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1c3b0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1c3c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1c3d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c3e0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1c3f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c400 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1c410 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1c420 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1c430 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1c440 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1c450 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1c460 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1c470 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1c480 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1c490 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1c4a0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1c4b0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1c4c0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1c4d0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1c4e0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1c4f0 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1c500 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1c510 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1c520 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1c530 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1c540 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1c550 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1c560 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1c570 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1c580 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1c590 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1c5a0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1c5b0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1c5c0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1c5d0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1c5e0 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
1c5f0 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
1c600 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
1c610 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
1c620 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
1c630 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
1c640 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1c650 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1c660 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
1c670 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1c680 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1c690 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1c6a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1c6b0 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
1c6c0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
1c6d0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
1c6e0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1c6f0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1c700 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1c710 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1c720 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1c730 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1c740 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
1c750 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1c760 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1c770 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c780 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1c790 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1c7a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1c7b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1c7c0 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1c7d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1c7e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1c7f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c800 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1c810 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1c820 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1c830 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c840 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1c850 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1c860 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1c870 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1c880 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1c890 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1c8a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c8b0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1c8c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1c8d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1c8e0 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1c8f0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1c900 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1c910 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1c920 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1c930 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1c940 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1c950 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1c960 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c970 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1c980 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1c990 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1c9a0 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1c9b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c9c0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1c9d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1c9e0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1c9f0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1ca00 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1ca10 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1ca20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1ca30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ca40 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1ca50 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1ca60 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1ca70 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1ca80 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1ca90 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1caa0 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1cab0 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1cac0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cad0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1cae0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1caf0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1cb00 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1cb10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1cb20 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1cb30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1cb40 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1cb50 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1cb60 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1cb70 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1cb80 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1cb90 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1cba0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1cbb0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1cbc0 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1cbd0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1cbe0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1cbf0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1cc00 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1cc10 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1cc20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1cc30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1cc40 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1cc50 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1cc60 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1cc70 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1cc80 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1cc90 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1cca0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1ccb0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1ccc0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ccd0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1cce0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ccf0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1cd00 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1cd10 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1cd20 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1cd30 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1cd40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1cd50 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1cd60 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1cd70 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1cd80 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1cd90 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1cda0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1cdb0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1cdc0 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1cdd0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1cde0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1cdf0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1ce00 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1ce10 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1ce20 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1ce30 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1ce40 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1ce50 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1ce60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1ce70 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1ce80 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1ce90 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1cea0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1ceb0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1cec0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1ced0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1cee0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1cef0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1cf00 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1cf10 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1cf20 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1cf30 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1cf40 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1cf50 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1cf60 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1cf70 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1cf80 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1cf90 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1cfa0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1cfb0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1cfc0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1cfd0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1cfe0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1cff0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1d000 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1d010 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d020 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1d030 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1d040 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1d050 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1d060 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1d070 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1d080 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1d090 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1d0a0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1d0b0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1d0c0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1d0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d0e0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1d0f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1d100 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1d110 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1d120 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1d130 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1d140 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1d150 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1d160 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1d170 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1d180 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1d190 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1d1a0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1d1b0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1d1c0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1d1d0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1d1e0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1d1f0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1d200 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1d210 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1d220 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1d230 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1d240 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d250 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1d260 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1d270 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1d280 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1d290 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1d2a0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1d2b0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1d2c0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1d2d0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1d2e0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1d2f0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1d300 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1d310 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1d320 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1d330 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1d340 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1d350 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1d360 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1d370 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1d380 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1d390 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1d3a0 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1d3b0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1d3c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1d3d0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1d3e0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1d3f0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1d400 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1d410 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1d420 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1d430 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1d440 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1d450 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1d460 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1d470 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1d480 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1d490 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1d4a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1d4b0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1d4c0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1d4d0 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1d4e0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1d4f0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1d500 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1d510 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1d520 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1d530 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1d540 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1d550 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1d560 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1d570 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1d580 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1d590 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1d5a0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1d5b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d5c0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1d5d0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1d5e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1d5f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1d600 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1d610 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1d620 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1d630 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1d640 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1d650 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1d660 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1d670 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1d680 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1d690 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1d6a0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1d6b0 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1d6c0 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1d6d0 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1d6e0 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1d6f0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1d700 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1d710 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1d720 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1d730 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d740 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1d750 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1d760 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1d770 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1d780 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d790 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1d7a0 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1d7b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d7c0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1d7d0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1d7e0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1d7f0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1d800 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1d810 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1d820 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1d830 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1d840 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1d850 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1d860 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1d870 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1d880 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1d890 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1d8a0 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1d8b0 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
1d8c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1d8d0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1d8e0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1d8f0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1d900 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1d910 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1d920 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1d930 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1d940 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1d950 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1d960 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
1d970 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1d980 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1d990 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1d9a0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
1d9b0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
1d9c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
1d9d0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
1d9e0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
1d9f0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
1da00 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
1da10 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1da20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
1da30 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
1da40 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1da50 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1da60 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
1da70 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
1da80 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1da90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
1daa0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
1dab0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
1dac0 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  s a [SQLITE_ROLL
1dad0 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  BACK | return co
1dae0 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  de].** from the 
1daf0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1db00 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1db10 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1db20 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1db30 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1db40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1db50 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1db60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1db70 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1db80 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1db90 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1dba0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1dbb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dbc0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1dbd0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1dbe0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1dbf0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1dc00 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1dc10 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1dc20 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1dc30 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1dc40 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1dc50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1dc60 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1dc70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1dc80 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1dc90 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1dca0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1dcb0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1dcc0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1dcd0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1dce0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1dcf0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1dd00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1dd10 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1dd20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1dd30 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1dd40 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1dd50 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1dd60 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1dd70 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1dd80 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1dd90 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1dda0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1ddb0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1ddc0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1ddd0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1dde0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1ddf0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1de00 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1de10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1de20 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1de30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1de40 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1de50 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1de60 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1de70 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1de80 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1de90 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1dea0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1deb0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1dec0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1ded0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1dee0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
1def0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
1df00 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
1df10 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
1df20 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
1df30 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
1df40 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
1df50 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
1df60 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1df70 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
1df80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1df90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1dfa0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1dfb0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1dfc0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1dfd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1dfe0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1dff0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e000 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e010 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e020 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1e030 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1e040 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e050 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e070 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1e080 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1e090 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1e0a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e0b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e0c0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1e0d0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1e0e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e0f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e110 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1e120 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1e130 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1e140 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e160 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1e170 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1e180 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1e190 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e1a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e1b0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1e1c0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1e1d0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1e1e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e1f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e200 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1e210 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1e220 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1e230 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1e250 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1e260 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1e270 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e280 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e290 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e2a0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1e2b0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1e2c0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e2d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e2e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e2f0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1e300 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1e310 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e320 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e330 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e340 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1e350 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1e360 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1e370 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e380 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1e390 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1e3a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e3b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e3c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e3d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1e3e0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1e3f0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1e400 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1e410 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e420 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1e430 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1e440 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1e450 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e460 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e470 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1e480 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1e490 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1e4a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e4b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e4c0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1e4d0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1e4e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1e4f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e500 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e510 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1e520 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1e530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e540 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e560 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1e570 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1e580 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1e590 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1e5a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e5b0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1e5c0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1e5d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1e5e0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1e5f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e600 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1e610 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1e620 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1e630 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e650 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1e660 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1e670 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1e680 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1e6a0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1e6b0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1e6c0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1e6d0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1e6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1e6f0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1e700 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1e710 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1e720 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1e740 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1e750 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1e760 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1e770 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e780 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1e790 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1e7a0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1e7b0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1e7c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e7d0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1e7e0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1e7f0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1e800 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e810 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e820 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1e830 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1e840 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1e850 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1e860 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e870 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e880 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1e890 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e8a0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1e8b0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1e8c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1e8d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1e8e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e8f0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1e900 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e910 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1e920 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1e930 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1e940 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1e950 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1e960 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1e970 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1e980 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1e990 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1e9a0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1e9b0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1e9c0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1e9d0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1e9e0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1e9f0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1ea00 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1ea10 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1ea20 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1ea30 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1ea40 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1ea50 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1ea60 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1ea70 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1ea80 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1ea90 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1eaa0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1eab0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1eac0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1ead0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1eae0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1eaf0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1eb00 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1eb10 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1eb20 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1eb30 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1eb40 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1eb50 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1eb60 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1eb70 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1eb80 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
1eb90 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1eba0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
1ebb0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
1ebc0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1ebd0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
1ebe0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
1ebf0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
1ec00 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
1ec10 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
1ec20 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
1ec30 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
1ec40 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
1ec50 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
1ec60 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
1ec70 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
1ec80 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
1ec90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1eca0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
1ecb0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
1ecc0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
1ecd0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
1ece0 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
1ecf0 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
1ed00 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
1ed10 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1ed20 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1ed30 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
1ed40 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
1ed50 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
1ed60 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
1ed70 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
1ed80 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
1ed90 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
1eda0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
1edb0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
1edc0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
1edd0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
1ede0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
1edf0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
1ee00 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1ee10 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
1ee20 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
1ee30 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
1ee40 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
1ee50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
1ee60 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
1ee70 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
1ee80 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
1ee90 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
1eea0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
1eeb0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
1eec0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
1eed0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1eee0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
1eef0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
1ef00 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
1ef10 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
1ef20 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
1ef30 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1ef40 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
1ef50 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
1ef60 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
1ef70 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1ef80 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
1ef90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
1efa0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1efb0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1efc0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1efd0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1efe0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1eff0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
1f000 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
1f010 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
1f020 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
1f030 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1f040 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
1f050 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
1f060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
1f070 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
1f080 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1f090 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
1f0a0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
1f0b0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
1f0c0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
1f0d0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
1f0e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
1f0f0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
1f100 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
1f110 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
1f120 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
1f130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
1f140 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
1f150 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
1f160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f170 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
1f180 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
1f190 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1f1a0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
1f1b0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
1f1c0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
1f1d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1f1e0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
1f1f0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
1f200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f210 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
1f220 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
1f230 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
1f240 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  he number of .**
1f250 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
1f260 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
1f270 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
1f280 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
1f290 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
1f2a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
1f2b0 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  back X..**.** ^O
1f2c0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
1f2d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
1f2e0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
1f2f0 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
1f300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f310 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
1f320 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
1f330 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
1f340 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
1f350 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
1f360 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
1f370 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
1f380 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
1f390 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1f3a0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
1f3b0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
1f3c0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
1f3d0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
1f3e0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
1f3f0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1f400 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1f410 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
1f420 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
1f430 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
1f440 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
1f450 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
1f460 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
1f470 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
1f480 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1f490 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1f4a0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
1f4b0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1f4c0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1f4d0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1f4e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1f4f0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1f500 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1f510 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1f520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f530 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1f540 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1f550 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1f560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f570 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1f580 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1f590 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1f5a0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
1f5b0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1f5c0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1f5d0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1f5e0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1f5f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1f600 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1f610 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1f620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1f630 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1f640 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1f650 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
1f660 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
1f670 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
1f680 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1f690 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1f6a0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1f6b0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1f6c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1f6d0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1f6e0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1f6f0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1f700 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1f710 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
1f720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f730 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1f740 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1f750 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1f760 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1f770 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1f780 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1f790 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1f7a0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1f7b0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1f7c0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1f7d0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1f7e0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1f7f0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1f800 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1f810 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1f820 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
1f830 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
1f840 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1f850 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1f860 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1f870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1f880 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1f890 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1f8a0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1f8b0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
1f8c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f8d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1f8e0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1f8f0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1f900 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1f910 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1f920 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1f930 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
1f940 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
1f950 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
1f960 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
1f970 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
1f980 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1f990 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1f9a0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1f9b0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1f9c0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1f9d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1f9e0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1f9f0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1fa00 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1fa10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1fa20 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1fa30 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1fa40 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1fa50 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1fa60 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1fa70 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1fa80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1fa90 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1faa0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1fab0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1fac0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1fad0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1fae0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1faf0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1fb00 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1fb10 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1fb20 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1fb30 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1fb40 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1fb50 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1fb60 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1fb70 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1fb80 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1fb90 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1fba0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
1fbb0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
1fbc0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1fbd0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
1fbe0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1fbf0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1fc00 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1fc10 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1fc20 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1fc30 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1fc40 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1fc50 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1fc60 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1fc70 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
1fc80 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
1fc90 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1fca0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
1fcb0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1fcc0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1fcd0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1fce0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1fcf0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1fd00 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1fd10 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1fd20 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1fd30 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1fd40 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1fd50 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1fd60 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1fd70 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1fd80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1fd90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1fda0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1fdb0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1fdc0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1fdd0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1fde0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1fdf0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1fe00 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1fe10 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1fe20 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1fe30 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1fe40 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1fe50 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1fe60 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1fe70 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1fe80 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1fe90 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1fea0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1feb0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1fec0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1fed0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1fee0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1fef0 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
1ff00 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1ff10 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1ff20 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1ff30 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1ff40 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1ff50 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1ff60 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
1ff70 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
1ff80 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1ff90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ffa0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1ffb0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1ffc0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1ffd0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
1ffe0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1fff0 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
20000 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
20010 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
20020 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
20030 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
20040 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
20050 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
20060 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
20070 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
20080 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20090 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
200a0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
200b0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
200c0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
200d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
200e0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
200f0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
20100 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
20110 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
20120 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
20130 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
20140 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
20150 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20160 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
20170 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
20180 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
20190 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
201a0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
201b0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
201c0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
201d0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
201e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
201f0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
20200 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
20210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20220 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
20230 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
20240 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
20250 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
20260 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
20270 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
20280 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
20290 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
202a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
202b0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
202c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
202d0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
202e0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
202f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
20300 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
20310 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
20320 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
20330 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
20340 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
20350 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
20360 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20370 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
20380 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
20390 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
203a0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
203b0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
203c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
203d0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
203e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
203f0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
20400 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20410 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
20420 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
20430 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20440 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
20450 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
20460 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
20470 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
20480 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
20490 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
204a0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
204b0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
204c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
204d0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
204e0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
204f0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
20500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20510 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
20520 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20530 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
20540 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
20550 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
20560 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
20570 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
20580 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
20590 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
205a0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
205b0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
205c0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
205d0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
205e0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
205f0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
20600 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
20610 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
20620 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
20630 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
20640 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
20650 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
20660 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
20670 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
20680 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
20690 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
206a0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
206b0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
206c0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
206d0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
206e0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
206f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20700 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
20710 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
20720 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
20730 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
20740 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
20750 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
20760 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
20770 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
20780 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
20790 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
207a0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
207b0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
207c0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
207d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
207e0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
207f0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
20800 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
20810 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
20820 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
20830 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
20840 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
20850 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20860 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
20870 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
20880 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
20890 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
208a0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
208b0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
208c0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
208d0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
208e0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
208f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
20900 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
20910 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
20920 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
20930 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
20940 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
20950 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
20960 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
20970 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
20980 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
20990 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
209a0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
209b0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
209c0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
209d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
209e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
209f0 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
20a00 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
20a10 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
20a20 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
20a30 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
20a40 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
20a50 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
20a60 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
20a70 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
20a80 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
20a90 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
20aa0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
20ab0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
20ac0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
20ad0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
20ae0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
20af0 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
20b00 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
20b10 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
20b20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
20b30 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
20b40 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
20b50 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
20b60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
20b70 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
20b80 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
20b90 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
20ba0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
20bb0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
20bc0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
20bd0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
20be0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
20bf0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
20c00 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
20c10 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
20c20 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
20c30 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
20c40 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
20c50 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
20c60 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
20c70 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
20c80 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
20c90 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
20ca0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
20cb0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
20cc0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
20cd0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
20ce0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
20cf0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
20d00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
20d10 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
20d20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20d30 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
20d40 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
20d50 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
20d60 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
20d70 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
20d80 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
20d90 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
20da0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
20db0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
20dc0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
20dd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
20de0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
20df0 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
20e00 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
20e10 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
20e20 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
20e30 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
20e40 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
20e50 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
20e60 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20e70 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
20e80 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
20e90 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
20ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20eb0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
20ec0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
20ed0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
20ee0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
20ef0 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
20f00 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
20f10 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
20f20 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
20f30 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
20f40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20f50 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
20f60 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
20f70 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
20f80 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
20f90 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
20fa0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
20fb0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
20fc0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
20fd0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
20fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20ff0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21000 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
21010 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
21020 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
21030 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
21040 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
21050 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
21060 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
21070 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
21080 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
21090 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
210a0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
210b0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
210c0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
210d0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
210e0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
210f0 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
21100 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
21110 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
21120 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
21130 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
21140 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
21150 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
21160 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
21170 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
21180 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
21190 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
211a0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
211b0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
211c0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
211d0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
211e0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
211f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21200 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
21210 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
21220 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
21230 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
21240 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
21250 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
21260 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
21270 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
21280 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
21290 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
212a0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
212b0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
212c0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
212d0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
212e0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
212f0 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
21300 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
21310 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
21320 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
21330 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
21340 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
21350 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
21360 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
21370 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
21380 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
21390 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
213a0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
213b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
213c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
213d0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
213e0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
213f0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
21400 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
21410 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
21420 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
21430 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
21440 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
21450 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21460 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
21470 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
21480 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
21490 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
214a0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
214b0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
214c0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
214d0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
214e0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
214f0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
21500 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
21510 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
21520 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
21530 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
21540 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21550 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
21560 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
21570 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
21580 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
21590 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
215a0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
215b0 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
215c0 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
215d0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
215e0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
215f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
21600 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
21610 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
21620 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
21630 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
21640 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
21650 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
21660 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
21670 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
21680 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
21690 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
216a0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
216b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
216c0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
216d0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
216e0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
216f0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
21700 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
21710 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
21720 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
21730 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
21740 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
21750 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
21760 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
21770 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
21780 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
21790 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
217a0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
217b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
217c0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
217d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
217e0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
217f0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
21800 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
21810 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21820 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21830 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
21840 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
21850 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
21860 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
21870 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
21880 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21890 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
218a0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
218b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
218c0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
218d0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
218e0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
218f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21900 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
21910 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
21920 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
21930 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
21940 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
21950 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
21960 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
21970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
21980 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
21990 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
219a0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
219b0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
219c0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
219d0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
219e0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
219f0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
21a00 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
21a10 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
21a20 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
21a30 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
21a40 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
21a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
21a60 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
21a70 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
21a80 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
21a90 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
21aa0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
21ab0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
21ac0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
21ad0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
21ae0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
21af0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
21b00 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
21b10 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
21b20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
21b30 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
21b40 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
21b50 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
21b60 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
21b70 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
21b80 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
21b90 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
21ba0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
21bb0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
21bc0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
21bd0 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
21be0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
21bf0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
21c00 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
21c10 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
21c20 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
21c30 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
21c40 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
21c50 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
21c60 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
21c70 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
21c80 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
21c90 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
21ca0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
21cb0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
21cc0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
21cd0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
21ce0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
21cf0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
21d00 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
21d10 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
21d20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
21d30 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21d40 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
21d50 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
21d60 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
21d70 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
21d80 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
21d90 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
21da0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
21db0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
21dc0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
21dd0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
21de0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
21df0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
21e00 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
21e10 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
21e20 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
21e30 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21e40 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
21e50 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
21e60 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
21e70 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
21e80 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
21e90 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
21ea0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
21eb0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
21ec0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
21ed0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
21ee0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
21ef0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
21f00 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
21f10 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
21f20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
21f30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
21f40 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
21f50 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
21f60 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
21f70 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
21f80 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
21f90 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
21fa0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
21fb0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
21fc0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
21fd0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
21fe0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
21ff0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
22000 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
22010 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22020 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
22030 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
22040 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
22050 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
22060 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
22070 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
22080 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
22090 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
220a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
220b0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
220c0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
220d0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
220e0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
220f0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
22100 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
22110 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
22120 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
22130 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
22140 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
22150 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
22160 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
22170 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
22180 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
22190 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
221a0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
221b0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
221c0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
221d0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
221e0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
221f0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
22200 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
22210 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
22220 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
22230 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
22240 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
22250 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
22260 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
22270 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
22280 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
22290 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
222a0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
222b0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
222c0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
222d0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
222e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
222f0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
22300 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
22310 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
22320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22330 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
22340 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
22350 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
22360 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
22370 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
22380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
22390 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
223a0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
223b0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
223c0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
223d0 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
223e0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
223f0 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
22400 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
22410 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
22420 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
22430 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
22440 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
22450 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
22460 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
22470 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
22480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
22490 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
224a0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
224b0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
224c0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
224d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
224e0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
224f0 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
22500 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
22510 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
22520 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
22530 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
22540 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
22550 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
22560 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
22570 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
22580 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
22590 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
225a0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
225b0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
225c0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
225d0 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
225e0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
225f0 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
22600 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
22610 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
22620 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
22630 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
22640 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
22650 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22660 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22670 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
22680 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
22690 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
226a0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
226b0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
226c0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
226d0 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
226e0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
226f0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22700 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
22710 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
22720 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
22730 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
22740 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
22750 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
22760 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
22770 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
22780 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
22790 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
227a0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
227b0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
227c0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
227d0 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
227e0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
227f0 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
22800 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
22810 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
22820 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
22830 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
22840 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
22850 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
22860 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
22870 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
22880 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
22890 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
228a0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
228b0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
228c0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
228d0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
228e0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
228f0 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
22900 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
22910 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
22920 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
22930 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
22940 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
22950 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
22960 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
22970 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
22980 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
22990 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
229a0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
229b0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
229c0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
229d0 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
229e0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
229f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
22a00 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
22a10 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
22a20 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
22a30 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
22a40 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22a50 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
22a60 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
22a70 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
22a80 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
22a90 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
22aa0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
22ab0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
22ac0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
22ad0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
22ae0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
22af0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
22b00 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
22b10 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
22b20 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
22b30 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
22b40 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
22b50 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
22b60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22b70 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
22b80 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
22b90 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
22ba0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22bb0 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
22bc0 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
22bd0 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
22be0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
22bf0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
22c00 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
22c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22c20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
22c30 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
22c40 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
22c50 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
22c60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
22c70 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
22c80 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
22c90 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
22ca0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
22cb0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
22cc0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
22cd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
22ce0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
22cf0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
22d00 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
22d10 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
22d20 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
22d30 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
22d40 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
22d50 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
22d60 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
22d70 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
22d80 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
22d90 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
22da0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
22db0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
22dc0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
22dd0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
22de0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
22df0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
22e00 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
22e10 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
22e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22e30 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
22e40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
22e50 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
22e60 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
22e70 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
22e80 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
22e90 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
22ea0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
22eb0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
22ec0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
22ed0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
22ee0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
22ef0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
22f00 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
22f10 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
22f20 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
22f30 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
22f40 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
22f50 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
22f60 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
22f70 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
22f80 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
22f90 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
22fa0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
22fb0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
22fc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
22fd0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
22fe0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
22ff0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
23000 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
23010 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
23020 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
23030 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
23040 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
23050 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
23060 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
23070 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
23080 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
23090 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
230a0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
230b0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
230c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
230d0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
230e0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
230f0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
23100 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
23110 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
23120 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
23130 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
23140 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
23150 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
23160 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
23170 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
23180 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
23190 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
231a0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
231b0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
231c0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
231d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
231e0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
231f0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
23200 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
23210 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
23220 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
23230 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
23240 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
23250 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
23260 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
23270 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
23280 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
23290 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
232a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
232b0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
232c0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
232d0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
232e0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
232f0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
23300 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
23310 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
23320 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
23330 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
23340 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
23350 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
23360 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
23370 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
23380 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
23390 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
233a0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
233b0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
233c0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
233d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
233e0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
233f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
23400 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
23410 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
23420 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23430 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
23440 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
23450 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
23460 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
23470 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
23480 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
23490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
234a0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
234b0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
234c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
234d0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
234e0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
234f0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
23500 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
23510 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
23520 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
23530 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
23540 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
23550 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
23560 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
23570 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
23580 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
23590 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
235a0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
235b0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
235c0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
235d0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
235e0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
235f0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
23600 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
23610 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23620 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
23630 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
23640 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
23650 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
23660 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
23670 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
23680 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
23690 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
236a0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
236b0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
236c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
236d0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
236e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
236f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
23700 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
23710 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
23720 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
23730 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
23740 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
23750 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
23760 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
23770 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
23780 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
23790 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
237a0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
237b0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
237c0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
237d0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
237e0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
237f0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
23800 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
23810 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
23820 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
23830 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
23840 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
23850 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
23860 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
23870 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
23880 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
23890 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
238a0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
238b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
238c0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
238d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
238e0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
238f0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
23900 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
23910 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
23920 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
23930 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
23940 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
23950 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
23960 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
23970 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
23980 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
23990 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
239a0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
239b0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
239c0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
239d0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
239e0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
239f0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
23a00 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
23a10 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
23a20 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
23a30 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
23a40 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
23a50 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
23a60 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
23a70 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
23a80 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
23a90 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
23aa0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
23ab0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
23ac0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
23ad0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
23ae0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
23af0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
23b00 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
23b10 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
23b20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
23b30 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
23b40 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
23b50 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
23b60 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
23b70 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
23b80 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
23b90 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
23ba0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
23bb0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
23bc0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
23bd0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
23be0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
23bf0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
23c00 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
23c10 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
23c20 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
23c30 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
23c40 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
23c50 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
23c60 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
23c70 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
23c80 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
23c90 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
23ca0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
23cb0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
23cc0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
23cd0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
23ce0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
23cf0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
23d00 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
23d10 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
23d20 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
23d30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
23d40 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
23d50 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
23d60 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
23d70 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
23d80 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
23d90 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
23da0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
23db0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
23dc0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
23dd0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
23de0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
23df0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
23e00 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
23e10 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
23e20 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
23e30 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
23e40 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
23e50 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
23e60 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
23e70 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
23e80 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
23e90 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
23ea0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
23eb0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
23ec0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
23ed0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23ee0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
23ef0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
23f00 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
23f10 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
23f20 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
23f30 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
23f40 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
23f50 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
23f60 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
23f70 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
23f80 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
23f90 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
23fa0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
23fb0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
23fc0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
23fd0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
23fe0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
23ff0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
24000 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
24010 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
24020 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
24030 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
24040 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
24050 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
24060 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
24070 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
24080 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
24090 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
240a0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
240b0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
240c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
240d0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
240e0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
240f0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
24100 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
24110 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
24120 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
24130 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
24140 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
24150 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
24160 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
24170 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24180 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
24190 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
241a0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
241b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
241c0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
241d0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
241e0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
241f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24200 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
24210 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
24220 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
24230 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
24240 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
24250 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
24260 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
24270 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
24280 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24290 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
242a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
242b0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
242c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
242d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
242e0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
242f0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
24300 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
24310 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
24320 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
24330 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
24340 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
24350 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
24360 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
24370 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24380 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
24390 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
243a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
243b0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
243c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
243d0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
243e0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
243f0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
24400 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24410 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
24420 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
24430 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
24440 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
24450 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24460 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
24470 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
24480 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
24490 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
244a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
244b0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
244c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
244d0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
244e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
244f0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
24500 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
24510 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
24520 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
24530 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
24540 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
24550 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
24560 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
24570 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
24580 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
24590 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
245a0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
245b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
245c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
245d0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
245e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
245f0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
24600 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24610 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
24620 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
24630 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
24640 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24650 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
24660 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24670 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
24680 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24690 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
246a0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
246b0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
246c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
246d0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
246e0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
246f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24700 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24710 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
24720 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
24730 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
24740 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
24750 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
24760 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
24770 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
24780 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
24790 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
247a0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
247b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
247c0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
247d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
247e0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
247f0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
24800 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
24810 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
24820 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
24830 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
24840 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
24850 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
24860 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24870 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24880 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24890 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
248a0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
248b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
248c0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
248d0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
248e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
248f0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
24900 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
24910 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
24920 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
24930 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
24940 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24950 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
24960 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
24970 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24980 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
24990 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
249a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
249b0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
249c0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
249d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
249e0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
249f0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
24a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24a10 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
24a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
24a30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24a40 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
24a50 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
24a60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24a70 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
24a80 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
24a90 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
24aa0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
24ab0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
24ac0 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
24ad0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
24ae0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
24af0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
24b00 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
24b10 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
24b20 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
24b30 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
24b40 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
24b50 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
24b60 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
24b70 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
24b80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
24b90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
24ba0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
24bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24bc0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
24bd0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
24be0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
24bf0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
24c00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
24c10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
24c20 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
24c30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24c40 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
24c50 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
24c60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
24c70 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
24c80 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
24c90 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
24ca0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
24cb0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
24cc0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
24cd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24ce0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
24cf0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
24d00 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
24d10 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
24d20 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
24d30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24d40 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
24d50 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
24d60 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
24d70 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
24d80 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
24d90 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
24da0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
24db0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
24dc0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
24dd0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
24de0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
24df0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
24e00 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
24e10 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
24e20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
24e30 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
24e40 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
24e50 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
24e60 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
24e70 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
24e80 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
24e90 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
24ea0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
24eb0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
24ec0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
24ed0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
24ee0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
24ef0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
24f00 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
24f10 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
24f20 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
24f30 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
24f40 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
24f50 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
24f60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
24f70 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
24f80 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
24f90 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
24fa0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
24fb0 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
24fc0 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
24fd0 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
24fe0 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
24ff0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
25000 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
25010 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
25020 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
25030 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
25040 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
25050 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
25060 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
25070 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
25080 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
25090 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
250a0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
250b0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
250c0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
250d0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
250e0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
250f0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
25100 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
25110 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
25120 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25130 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
25140 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
25150 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
25160 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
25170 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
25180 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
25190 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
251a0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
251b0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
251c0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
251d0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
251e0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
251f0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
25200 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
25210 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
25220 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
25230 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
25240 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
25250 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
25260 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
25270 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
25280 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
25290 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
252a0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
252b0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
252c0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
252d0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
252e0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
252f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
25300 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
25310 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
25320 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
25330 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
25340 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
25350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25360 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
25370 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
25380 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
25390 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
253a0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
253b0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
253c0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
253d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
253e0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
253f0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
25400 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
25410 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
25420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25430 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
25440 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
25450 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
25460 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
25470 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
25480 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
25490 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
254a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
254b0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
254c0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
254d0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
254e0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
254f0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
25500 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
25510 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
25520 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
25530 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
25540 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
25550 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
25560 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
25570 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
25580 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
25590 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
255a0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
255b0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
255c0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
255d0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
255e0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
255f0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
25600 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
25610 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
25620 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
25630 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
25640 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
25650 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
25660 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
25670 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
25680 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
25690 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
256a0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
256b0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
256c0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
256d0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
256e0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
256f0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
25700 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
25710 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
25720 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25730 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
25740 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
25750 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
25760 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
25770 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
25780 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
25790 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
257a0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
257b0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
257c0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
257d0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
257e0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
257f0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
25800 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
25810 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
25820 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
25830 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
25840 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
25850 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
25860 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
25870 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
25880 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
25890 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
258a0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
258b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
258c0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
258d0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
258e0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
258f0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
25900 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
25910 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
25920 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
25930 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
25940 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
25950 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
25960 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
25970 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
25980 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
25990 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
259a0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
259b0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
259c0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
259d0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
259e0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
259f0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
25a00 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
25a10 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
25a20 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
25a30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
25a40 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
25a50 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
25a60 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
25a70 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
25a80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
25a90 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
25aa0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
25ab0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
25ac0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
25ad0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
25ae0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
25af0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
25b00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
25b10 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
25b20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
25b30 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
25b40 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
25b50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
25b60 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
25b70 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
25b80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
25b90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
25ba0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
25bb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25bc0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
25bd0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
25be0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
25bf0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
25c00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
25c10 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
25c20 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
25c30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
25c40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25c50 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
25c60 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
25c70 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
25c80 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
25c90 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
25ca0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
25cb0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
25cc0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
25cd0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
25ce0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
25cf0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
25d00 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
25d10 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
25d20 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
25d30 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
25d40 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
25d50 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
25d60 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
25d70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
25d80 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
25d90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
25da0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25db0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
25dc0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
25dd0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
25de0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
25df0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
25e00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
25e10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
25e20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
25e30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
25e40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
25e50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
25e60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
25e70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
25e80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
25e90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25ea0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
25eb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25ec0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25ed0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25ee0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
25ef0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25f00 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
25f10 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
25f20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
25f30 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
25f40 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
25f50 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
25f60 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
25f70 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
25f80 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25f90 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
25fa0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25fb0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25fc0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25fd0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
25fe0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
25ff0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
26000 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
26010 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26020 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
26030 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
26040 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
26050 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
26060 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
26070 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
26080 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
26090 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
260a0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
260b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
260c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
260d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
260e0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
260f0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
26100 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
26110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26120 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
26130 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
26140 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
26150 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
26160 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26170 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
26180 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
26190 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
261a0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
261b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
261c0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
261d0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
261e0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
261f0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
26200 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
26210 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
26220 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
26230 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
26240 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
26250 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
26260 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
26270 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
26280 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
26290 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
262a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
262b0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
262c0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
262d0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
262e0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
262f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
26300 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
26310 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
26320 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
26330 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
26340 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
26350 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
26360 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
26370 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
26380 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
26390 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
263a0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
263b0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
263c0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
263d0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
263e0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
263f0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
26400 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
26410 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
26420 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
26430 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
26440 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
26450 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
26460 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
26470 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
26480 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
26490 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
264a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
264b0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
264c0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
264d0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
264e0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
264f0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
26500 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
26510 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
26520 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
26530 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
26540 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
26550 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
26560 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
26570 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
26580 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
26590 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
265a0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
265b0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
265c0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
265d0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
265e0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
265f0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
26600 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26610 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
26620 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
26630 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
26640 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
26650 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
26660 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
26670 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
26680 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
26690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
266a0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
266b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
266c0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
266d0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
266e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
266f0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
26700 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
26710 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
26720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26730 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
26740 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
26750 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
26760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
26770 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
26780 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
26790 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
267a0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
267b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
267c0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
267d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
267e0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
267f0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
26800 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
26810 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
26820 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
26830 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
26840 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
26850 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
26860 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
26870 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
26880 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
26890 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
268a0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
268b0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
268c0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
268d0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
268e0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
268f0 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
26900 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
26910 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
26920 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
26930 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
26940 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
26950 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
26960 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
26970 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
26980 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
26990 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
269a0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
269b0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
269c0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
269d0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
269e0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
269f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
26a00 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
26a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26a20 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
26a30 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
26a40 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
26a50 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
26a60 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
26a70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26a80 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
26a90 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
26aa0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26ab0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
26ac0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
26ad0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
26ae0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
26af0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
26b00 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
26b10 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
26b20 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
26b30 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
26b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26b50 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
26b60 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
26b70 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
26b80 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
26b90 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
26ba0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
26bb0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
26bc0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
26bd0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
26be0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
26bf0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
26c00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26c10 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
26c20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
26c30 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
26c40 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
26c50 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
26c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
26c70 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
26c80 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
26c90 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
26ca0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
26cb0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
26cc0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
26cd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26ce0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
26cf0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
26d00 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
26d10 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
26d20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
26d30 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
26d40 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
26d50 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
26d60 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
26d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26d80 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
26d90 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
26da0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
26db0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26dc0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
26dd0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
26de0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
26df0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
26e00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
26e10 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
26e20 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
26e30 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
26e40 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
26e50 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
26e60 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
26e70 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
26e80 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
26e90 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
26ea0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
26eb0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
26ec0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
26ed0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
26ee0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
26ef0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
26f00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
26f10 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
26f20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
26f30 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
26f40 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
26f50 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
26f60 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
26f70 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
26f80 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
26f90 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
26fa0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
26fb0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
26fc0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
26fd0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
26fe0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
26ff0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
27000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27010 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
27020 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
27030 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
27040 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
27050 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
27060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
27080 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
27090 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
270a0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
270b0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
270c0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
270d0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
270e0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
270f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
27100 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
27110 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
27120 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
27130 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
27140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
27150 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
27160 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
27170 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
27180 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
27190 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
271a0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
271b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
271c0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
271d0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
271e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
271f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27200 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
27210 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
27220 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
27230 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
27240 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
27250 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
27260 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
27270 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
27280 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
27290 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
272a0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
272b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
272c0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
272d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
272e0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
272f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27300 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27320 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
27330 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
27340 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
27350 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
27360 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
27370 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
27380 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27390 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
273a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
273b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
273c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
273d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
273e0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
273f0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
27400 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
27410 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
27420 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
27430 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
27440 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
27450 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
27460 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
27470 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
27480 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
27490 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
274a0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
274b0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
274c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
274d0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
274e0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
274f0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
27500 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
27510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
27520 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
27530 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27540 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
27550 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
27560 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
27570 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
27580 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
27590 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
275a0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
275b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
275c0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
275d0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
275e0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
275f0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
27600 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
27610 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
27620 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
27630 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
27640 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
27650 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
27660 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
27670 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
27680 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
27690 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
276a0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
276b0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
276c0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
276d0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
276e0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
276f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
27700 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
27710 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
27720 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27730 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
27740 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27750 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
27760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
27770 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
27780 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
27790 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
277a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
277b0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
277c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
277d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
277e0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
277f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
27800 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
27810 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
27820 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
27830 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
27840 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
27850 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
27860 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
27870 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
27880 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
27890 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
278a0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
278b0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
278c0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
278d0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
278e0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
278f0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
27900 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
27910 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27920 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
27930 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
27940 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
27950 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
27960 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
27970 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
27980 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
27990 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
279a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
279b0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
279c0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
279d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
279e0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
279f0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
27a00 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
27a10 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
27a20 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
27a30 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
27a40 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
27a50 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
27a60 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
27a70 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
27a80 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
27a90 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
27aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
27ab0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
27ac0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
27ad0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
27ae0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
27af0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
27b00 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
27b10 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
27b20 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
27b30 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
27b40 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
27b50 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
27b60 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
27b70 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
27b80 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
27b90 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
27ba0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
27bb0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
27bc0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
27bd0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
27be0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
27bf0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
27c00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27c10 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
27c20 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
27c30 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
27c40 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
27c50 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
27c60 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
27c70 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
27c80 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
27c90 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
27ca0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27cb0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
27cc0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
27cd0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
27ce0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
27cf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
27d00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
27d10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
27d20 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
27d30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
27d40 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
27d50 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
27d60 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
27d70 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
27d80 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
27d90 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
27da0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
27db0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
27dc0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
27dd0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
27de0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
27df0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
27e00 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
27e10 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
27e20 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
27e30 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
27e40 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
27e50 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
27e60 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
27e70 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
27e80 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
27e90 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
27ea0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
27eb0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
27ec0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27ed0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
27ee0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
27ef0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
27f00 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
27f10 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
27f20 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
27f30 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
27f40 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
27f50 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
27f60 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
27f70 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
27f80 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
27f90 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
27fa0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
27fb0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
27fc0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
27fd0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
27fe0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27ff0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
28000 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
28010 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28020 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
28030 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
28040 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
28050 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
28060 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
28070 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
28080 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
28090 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
280a0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
280b0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
280c0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
280d0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
280e0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
280f0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
28100 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
28110 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
28120 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
28130 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
28140 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
28150 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
28160 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
28170 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
28180 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
28190 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
281a0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
281b0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
281c0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
281d0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
281e0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
281f0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
28200 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
28210 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
28220 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
28230 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
28240 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
28250 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
28260 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
28270 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
28280 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
28290 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
282a0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
282b0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
282c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
282d0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
282e0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
282f0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
28300 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
28310 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
28320 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
28330 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
28340 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
28350 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28360 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
28370 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
28380 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
28390 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
283a0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
283b0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
283c0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
283d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
283e0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
283f0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
28400 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
28410 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
28420 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
28430 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
28440 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
28450 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
28460 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
28470 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
28480 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
28490 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
284a0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
284b0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
284c0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
284d0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
284e0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
284f0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
28500 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
28510 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
28520 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
28530 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
28540 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
28550 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28560 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
28570 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
28580 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
28590 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
285a0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
285b0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
285c0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
285d0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
285e0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
285f0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
28600 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
28610 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
28620 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
28630 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28640 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28650 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
28660 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
28670 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
28680 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
28690 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
286a0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
286b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
286c0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
286d0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
286e0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
286f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
28700 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28710 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
28720 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
28730 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
28740 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
28750 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
28760 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28770 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
28780 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
28790 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
287a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
287b0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
287c0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
287d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
287e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
287f0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
28800 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
28810 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
28820 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28830 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28840 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
28850 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28860 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
28870 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
28880 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28890 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
288a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
288b0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
288c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
288d0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
288e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
288f0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
28900 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
28910 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
28920 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
28930 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
28940 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
28950 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
28960 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
28970 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
28980 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
28990 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
289a0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
289b0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
289c0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
289d0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
289e0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
289f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28a00 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
28a10 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
28a20 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
28a30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
28a40 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
28a50 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
28a60 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
28a70 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
28a80 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
28a90 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
28aa0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
28ab0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
28ac0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
28ad0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
28ae0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
28af0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
28b00 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
28b10 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
28b20 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
28b30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28b40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28b50 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
28b60 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28b70 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28b80 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
28b90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28ba0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28bb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28bc0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28bd0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
28be0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28bf0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
28c00 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
28c10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28c20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28c30 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
28c40 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
28c50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28c60 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
28c70 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
28c80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28c90 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
28ca0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
28cb0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
28cc0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
28cd0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
28ce0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
28cf0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
28d00 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
28d10 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
28d20 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
28d30 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
28d40 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
28d50 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
28d60 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
28d70 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
28d80 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
28d90 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
28da0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
28db0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
28dc0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
28dd0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
28de0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
28df0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
28e00 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
28e10 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
28e20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
28e30 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
28e40 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
28e50 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
28e60 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
28e70 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
28e80 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
28e90 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
28ea0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
28eb0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
28ec0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
28ed0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
28ee0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
28ef0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
28f00 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
28f10 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
28f20 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
28f30 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
28f40 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
28f50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28f60 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
28f70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28f80 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
28f90 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
28fa0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28fb0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
28fc0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
28fd0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28fe0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
28ff0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29000 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29010 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29020 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
29030 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
29040 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
29050 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
29060 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
29070 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
29080 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
29090 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
290a0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
290b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
290c0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
290d0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
290e0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
290f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29100 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29110 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
29120 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
29130 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
29140 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
29150 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
29160 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
29170 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
29180 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
29190 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
291a0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
291b0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
291c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
291d0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
291e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
291f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29200 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
29210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29220 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
29230 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
29240 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29250 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29260 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
29270 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29280 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
29290 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
292a0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
292b0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
292c0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
292d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
292e0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
292f0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
29300 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
29310 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
29320 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
29330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
29340 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
29350 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
29360 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
29370 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
29380 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
29390 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
293a0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
293b0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
293c0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
293d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
293e0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
293f0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
29400 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
29410 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
29420 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
29430 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29440 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
29450 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
29460 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
29470 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
29480 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
29490 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
294a0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
294b0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
294c0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
294d0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
294e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
294f0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
29500 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
29510 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
29520 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
29530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29540 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
29550 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
29560 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
29570 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
29580 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
29590 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
295a0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
295b0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
295c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
295d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
295e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
295f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29600 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
29610 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
29620 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
29630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
29640 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
29650 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
29660 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
29670 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
29680 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
29690 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
296a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
296b0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
296c0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
296d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
296e0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
296f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
29700 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
29710 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
29720 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
29730 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
29740 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
29750 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
29760 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
29770 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29780 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
29790 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
297a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
297b0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
297c0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
297d0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
297e0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
297f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
29800 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
29810 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
29820 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
29830 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
29840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29850 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
29860 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
29870 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
29880 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
29890 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
298a0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
298b0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
298c0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
298d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
298e0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
298f0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
29900 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
29910 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
29920 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
29930 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
29940 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
29950 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
29960 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
29970 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
29980 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
29990 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
299a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
299b0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
299c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
299d0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
299e0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
299f0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
29a00 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
29a10 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
29a20 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
29a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
29a40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29a50 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
29a60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29a70 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
29a80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
29a90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29aa0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
29ab0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
29ac0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
29ad0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
29ae0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
29af0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
29b00 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
29b10 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
29b20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
29b30 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
29b40 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
29b50 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
29b60 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
29b70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
29b80 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
29b90 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
29ba0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
29bb0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
29bc0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
29bd0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
29be0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
29bf0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
29c00 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
29c10 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
29c20 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
29c30 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
29c40 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
29c50 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
29c60 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
29c70 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
29c80 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
29c90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29ca0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
29cb0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
29cc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29cd0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
29ce0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
29cf0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
29d00 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
29d10 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
29d20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29d30 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
29d40 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
29d50 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
29d60 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
29d70 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
29d80 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
29d90 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
29da0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
29db0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
29dc0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
29dd0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
29de0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
29df0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
29e00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29e10 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
29e20 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
29e30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29e40 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
29e50 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
29e60 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
29e70 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
29e80 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
29e90 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
29ea0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
29eb0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
29ec0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
29ed0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
29ee0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
29ef0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
29f00 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
29f10 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
29f20 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
29f30 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
29f40 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
29f50 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
29f60 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
29f70 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
29f80 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
29f90 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
29fa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
29fb0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
29fc0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
29fd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
29fe0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
29ff0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2a000 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2a010 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2a020 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2a030 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2a040 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2a050 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2a060 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2a070 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2a080 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2a090 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2a0a0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2a0b0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2a0c0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2a0d0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2a0e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2a0f0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2a100 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2a110 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2a120 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2a130 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2a140 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2a150 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2a160 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2a170 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2a180 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2a190 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2a1a0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2a1b0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2a1c0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2a1d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a1e0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2a1f0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2a200 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2a210 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2a220 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2a230 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2a240 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2a250 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2a260 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2a270 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2a280 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2a290 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2a2a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a2b0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2a2c0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2a2d0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2a2e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a2f0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
2a300 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a310 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2a320 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a330 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2a340 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2a350 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2a360 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a370 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2a380 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2a390 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2a3a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a3b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2a3c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2a3d0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2a3e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a3f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a400 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2a410 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a420 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2a430 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2a440 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
2a450 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a460 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2a470 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
2a480 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
2a490 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2a4a0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
2a4b0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
2a4c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a4d0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
2a4e0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
2a4f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
2a500 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
2a510 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
2a520 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
2a530 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
2a540 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
2a550 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
2a560 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2a570 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
2a580 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
2a590 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
2a5a0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
2a5b0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
2a5c0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2a5d0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
2a5e0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2a5f0 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
2a600 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2a610 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
2a620 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2a630 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
2a640 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
2a650 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2a660 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
2a670 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
2a680 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
2a690 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
2a6a0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
2a6b0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
2a6c0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
2a6d0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
2a6e0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
2a6f0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
2a700 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
2a710 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
2a720 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
2a730 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
2a740 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
2a750 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
2a760 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
2a770 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
2a780 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
2a790 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2a7a0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
2a7b0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
2a7c0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
2a7d0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
2a7e0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
2a7f0 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
2a800 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
2a810 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
2a820 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
2a830 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
2a840 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
2a850 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
2a860 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
2a870 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
2a880 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
2a890 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
2a8a0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
2a8b0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
2a8c0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
2a8d0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
2a8e0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
2a8f0 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
2a900 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a910 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2a920 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a930 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a940 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2a950 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a960 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2a970 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2a980 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2a990 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
2a9a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a9b0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2a9c0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2a9d0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2a9e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2a9f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2aa00 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2aa10 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2aa20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2aa30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2aa40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2aa50 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2aa60 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2aa70 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2aa80 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2aa90 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2aaa0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2aab0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2aac0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2aad0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2aae0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2aaf0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2ab00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2ab10 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2ab20 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2ab30 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2ab40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ab50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ab60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ab70 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2ab80 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2ab90 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2aba0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2abb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2abc0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2abd0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2abe0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2abf0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2ac00 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2ac10 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2ac20 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2ac30 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2ac40 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2ac50 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2ac60 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2ac70 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2ac80 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2ac90 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2aca0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2acb0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2acc0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2acd0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2ace0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2acf0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2ad00 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2ad10 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2ad20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2ad30 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2ad40 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2ad50 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2ad60 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2ad70 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2ad80 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2ad90 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2ada0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2adb0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2adc0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2add0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2ade0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2adf0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2ae00 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2ae10 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2ae20 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2ae30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2ae40 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2ae50 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2ae60 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2ae70 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2ae80 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2ae90 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2aea0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2aeb0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2aec0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2aed0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2aee0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2aef0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2af00 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2af10 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2af20 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2af30 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2af40 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2af50 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2af60 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2af70 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2af80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2af90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2afa0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2afb0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2afc0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2afd0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2afe0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2aff0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2b000 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2b010 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2b020 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2b030 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2b040 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2b050 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2b060 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2b070 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2b080 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2b090 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2b0a0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2b0b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2b0c0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2b0d0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2b0e0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2b0f0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2b100 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2b110 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2b120 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2b130 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2b140 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2b150 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2b160 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2b170 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2b180 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2b190 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2b1a0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2b1b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2b1c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2b1d0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2b1e0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2b1f0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2b200 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2b210 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2b220 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2b230 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2b240 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2b250 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2b260 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2b270 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2b280 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2b290 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2b2a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2b2b0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2b2c0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2b2d0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2b2e0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2b2f0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2b300 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2b310 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2b320 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
2b330 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
2b340 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
2b350 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
2b360 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
2b370 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
2b380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b390 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
2b3a0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
2b3b0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2b3c0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
2b3d0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
2b3e0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
2b3f0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
2b400 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2b410 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
2b420 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
2b430 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
2b440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b450 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
2b460 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
2b470 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
2b480 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
2b490 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
2b4a0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
2b4b0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
2b4c0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
2b4d0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
2b4e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2b4f0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
2b500 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
2b510 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
2b520 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
2b530 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2b540 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
2b550 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2b560 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
2b570 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
2b580 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
2b590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b5a0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
2b5b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2b5c0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
2b5d0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2b5e0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
2b5f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2b600 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
2b610 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
2b620 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2b630 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2b640 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b650 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2b660 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2b670 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2b680 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2b690 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2b6a0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2b6b0 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2b6c0 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2b6d0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2b6e0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2b6f0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2b700 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2b710 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2b720 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2b730 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2b740 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2b750 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2b760 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2b770 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2b780 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2b790 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2b7a0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2b7b0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2b7c0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2b7d0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2b7e0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2b7f0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2b800 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2b810 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2b820 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2b830 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2b840 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2b850 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2b860 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2b870 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b880 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2b890 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2b8a0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2b8b0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2b8c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2b8d0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2b8e0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2b8f0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2b900 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2b910 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2b920 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2b930 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2b940 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2b950 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2b960 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2b970 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2b980 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2b990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b9a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2b9b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2b9c0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2b9d0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2b9e0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2b9f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ba00 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2ba10 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2ba20 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2ba30 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2ba40 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2ba50 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2ba60 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2ba70 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2ba80 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2ba90 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
2baa0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2bab0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2bac0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2bad0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2bae0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2baf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2bb00 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2bb10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2bb20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2bb30 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2bb40 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2bb50 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2bb60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bb70 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2bb80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bb90 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2bba0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2bbb0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2bbc0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2bbd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2bbe0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2bbf0 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2bc00 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2bc10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2bc20 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2bc30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bc40 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2bc50 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2bc60 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2bc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2bc80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2bc90 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2bca0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2bcb0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2bcc0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2bcd0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2bce0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2bcf0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2bd00 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2bd10 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2bd20 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2bd30 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2bd40 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2bd50 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2bd60 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2bd70 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2bd80 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2bd90 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2bda0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2bdb0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2bdc0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2bdd0 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2bde0 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2bdf0 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2be00 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2be10 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2be20 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2be30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
2be40 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2be50 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2be60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2be70 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2be80 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2be90 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2bea0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2beb0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2bec0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2bed0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2bee0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2bef0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2bf00 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2bf10 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2bf20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2bf30 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2bf40 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2bf50 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2bf60 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2bf70 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2bf80 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2bf90 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2bfa0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2bfb0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2bfc0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2bfd0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2bfe0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2bff0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2c000 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2c010 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2c020 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2c030 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2c040 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2c050 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2c060 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2c070 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2c080 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2c090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2c0a0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2c0b0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2c0c0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2c0d0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2c0e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2c0f0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2c100 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2c110 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2c120 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2c130 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2c140 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2c150 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2c160 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2c170 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2c180 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2c190 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2c1a0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2c1b0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2c1c0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
2c1d0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
2c1e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2c1f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2c200 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2c210 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2c220 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2c230 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2c240 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2c250 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2c260 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2c270 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2c280 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2c290 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c2a0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2c2b0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2c2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2c2d0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2c2e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2c2f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c300 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2c310 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2c320 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2c330 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2c340 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2c350 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2c360 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2c370 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2c380 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2c390 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2c3a0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2c3b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2c3c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c3d0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2c3e0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2c3f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2c400 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2c410 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2c420 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2c430 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2c440 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2c450 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2c460 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2c470 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2c480 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2c490 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2c4a0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2c4b0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2c4c0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2c4d0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2c4e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2c4f0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2c500 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2c510 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2c520 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2c530 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c540 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2c550 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2c560 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2c570 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2c580 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2c590 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c5a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2c5b0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2c5c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2c5d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2c5e0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2c5f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2c600 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2c610 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2c620 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2c630 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2c640 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2c650 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2c660 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2c670 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2c680 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2c690 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2c6a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2c6b0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2c6c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2c6d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2c6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2c6f0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2c700 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2c710 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2c720 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2c730 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2c740 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2c750 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2c760 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2c770 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2c780 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2c790 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2c7a0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2c7b0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2c7c0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2c7d0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2c7e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2c7f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c800 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2c810 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2c820 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2c830 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2c840 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2c850 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2c860 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2c870 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2c880 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2c890 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2c8a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2c8b0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2c8c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2c8d0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2c8e0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2c8f0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2c900 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2c910 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2c920 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c930 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2c940 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2c950 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2c960 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2c970 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2c980 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c990 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2c9a0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2c9b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c9c0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2c9d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2c9e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2c9f0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2ca00 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2ca10 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2ca20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ca30 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2ca40 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2ca50 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2ca60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ca70 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2ca80 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2ca90 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2caa0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2cab0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2cac0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2cad0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2cae0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2caf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2cb00 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2cb10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cb20 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2cb30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cb40 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2cb50 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2cb60 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2cb70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2cb80 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2cb90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2cba0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2cbb0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2cbc0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2cbd0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2cbe0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2cbf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cc00 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2cc10 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2cc20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2cc30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2cc40 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2cc50 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2cc60 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2cc70 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2cc80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2cc90 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2cca0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2ccb0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2ccc0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2ccd0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2cce0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2ccf0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2cd00 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2cd10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2cd20 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2cd30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2cd40 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2cd50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
2cd60 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
2cd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cd80 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
2cd90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cda0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
2cdb0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
2cdc0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
2cdd0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2cde0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
2cdf0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
2ce00 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2ce10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2ce20 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2ce30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ce40 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
2ce50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2ce60 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
2ce70 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
2ce80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2ce90 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
2cea0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2ceb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cec0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2ced0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2cee0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2cef0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2cf00 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
2cf10 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
2cf20 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2cf30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cf40 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2cf50 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2cf60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2cf70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
2cf80 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2cf90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2cfa0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2cfb0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2cfc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2cfd0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2cfe0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cff0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2d000 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2d010 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2d020 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2d030 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2d040 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2d050 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2d060 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d070 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2d080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d090 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2d0a0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2d0b0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2d0c0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2d0d0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2d0e0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2d0f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d100 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2d110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d120 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2d130 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2d140 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2d150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2d160 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2d170 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2d180 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2d190 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2d1a0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2d1b0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2d1c0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2d1d0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2d1e0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2d1f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2d200 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2d210 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2d220 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2d230 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2d240 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2d250 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2d260 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2d270 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2d280 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2d290 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2d2a0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2d2b0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2d2c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2d2d0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2d2e0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2d2f0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2d300 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2d310 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2d320 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2d330 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2d340 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2d350 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2d360 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2d370 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2d380 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2d390 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2d3a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2d3b0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2d3c0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2d3d0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2d3e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2d3f0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2d400 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2d410 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2d420 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2d430 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2d440 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2d450 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2d460 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2d470 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2d480 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2d490 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2d4a0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2d4b0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2d4c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2d4d0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2d4e0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2d4f0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2d500 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2d510 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2d520 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2d530 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2d540 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2d550 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2d560 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2d570 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2d580 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2d590 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2d5a0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2d5b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2d5c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2d5d0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2d5e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2d5f0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2d600 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2d610 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2d620 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2d630 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2d640 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2d650 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2d660 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2d670 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2d680 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2d690 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2d6a0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2d6b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2d6c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2d6d0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2d6e0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2d6f0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2d700 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2d710 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2d720 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2d730 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2d740 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2d750 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2d760 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2d770 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2d780 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2d790 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2d7a0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2d7b0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2d7c0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2d7d0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2d7e0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2d7f0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2d800 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2d810 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2d820 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2d830 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2d840 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2d850 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2d860 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2d870 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2d880 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2d890 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2d8a0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2d8b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d8c0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2d8d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2d8e0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2d8f0 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2d900 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2d910 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2d920 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2d930 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2d940 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2d950 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2d960 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2d970 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2d980 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2d990 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2d9a0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2d9b0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2d9c0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2d9d0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2d9e0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2d9f0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2da00 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2da10 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2da20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2da30 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2da40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2da50 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2da60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2da70 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2da80 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2da90 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2daa0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2dab0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2dac0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2dad0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2dae0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2daf0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2db00 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2db10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2db20 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2db30 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2db40 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2db50 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2db60 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2db70 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2db80 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2db90 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2dba0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2dbb0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2dbc0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2dbd0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2dbe0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2dbf0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2dc00 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2dc10 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2dc20 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2dc30 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2dc40 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2dc50 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2dc60 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2dc70 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2dc80 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2dc90 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2dca0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2dcb0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2dcc0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2dcd0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2dce0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2dcf0 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2dd00 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2dd10 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2dd20 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2dd30 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2dd40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2dd50 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2dd60 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2dd70 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2dd80 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2dd90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2dda0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2ddb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2ddc0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2ddd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2dde0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2ddf0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2de00 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2de10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2de20 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2de30 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2de40 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2de50 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2de60 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2de70 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2de80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2de90 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2dea0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2deb0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2dec0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2ded0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2dee0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2def0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2df00 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2df10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2df20 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2df30 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2df40 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2df50 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2df60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2df70 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2df80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2df90 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2dfa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dfb0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2dfc0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2dfd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dfe0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2dff0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2e000 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2e010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2e020 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2e030 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2e040 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2e050 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2e060 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2e070 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2e080 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2e090 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2e0a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2e0b0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2e0c0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2e0d0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2e0e0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2e0f0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2e100 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2e110 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2e120 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2e130 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
2e140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e150 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2e160 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2e170 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2e180 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2e190 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2e1a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2e1b0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2e1c0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2e1d0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2e1e0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2e1f0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2e200 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2e210 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2e220 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2e230 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2e240 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2e250 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2e260 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2e270 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2e280 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2e290 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2e2a0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2e2b0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2e2c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2e2d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2e2e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e2f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2e300 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2e310 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e320 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2e330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e340 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2e350 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2e360 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2e370 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2e380 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e390 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2e3a0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2e3b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e3c0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2e3d0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2e3e0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2e3f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e400 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2e410 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2e420 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2e430 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e440 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2e450 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2e460 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2e470 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2e490 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2e4a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e4b0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2e4c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e4d0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2e4e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e4f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e500 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2e510 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2e520 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2e530 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2e540 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2e550 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2e560 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e570 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2e580 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e590 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2e5a0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2e5b0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2e5c0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2e5d0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2e5e0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2e5f0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2e600 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2e610 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2e620 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2e630 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2e640 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2e650 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2e660 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e670 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2e680 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2e690 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2e6a0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2e6b0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2e6c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e6d0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2e6e0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2e6f0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2e700 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2e710 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2e720 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2e730 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2e740 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2e750 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2e760 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2e770 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2e780 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2e790 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2e7a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2e7b0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2e7c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2e7d0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2e7e0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2e7f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2e800 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2e810 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2e820 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2e830 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2e840 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2e850 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2e860 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2e870 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2e880 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2e890 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2e8a0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2e8b0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2e8c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2e8d0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2e8e0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2e8f0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2e900 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2e910 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2e920 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2e930 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2e940 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2e950 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2e960 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2e970 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2e980 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2e990 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2e9a0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2e9b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2e9c0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2e9d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2e9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2e9f0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2ea00 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2ea10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ea20 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2ea30 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2ea40 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2ea50 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2ea60 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2ea70 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2ea80 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2ea90 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2eaa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2eab0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2eac0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2ead0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2eae0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2eaf0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2eb00 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2eb10 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2eb20 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2eb30 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2eb40 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2eb50 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2eb60 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2eb70 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2eb80 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2eb90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eba0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2ebb0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2ebc0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2ebd0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2ebe0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2ebf0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2ec00 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2ec10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ec20 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2ec30 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2ec40 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2ec50 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2ec60 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2ec70 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2ec80 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2ec90 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2eca0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2ecb0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2ecc0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2ecd0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2ece0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2ecf0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2ed00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ed10 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2ed20 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2ed30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2ed40 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2ed50 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2ed60 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2ed70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ed80 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2ed90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2eda0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2edb0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2edc0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2edd0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2ede0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2edf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2ee00 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2ee10 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2ee20 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2ee30 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2ee40 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2ee50 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2ee60 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2ee70 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2ee80 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2ee90 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2eea0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2eeb0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2eec0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2eed0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2eee0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2eef0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2ef00 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2ef10 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2ef20 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2ef30 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2ef40 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2ef50 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2ef60 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2ef70 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2ef80 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2ef90 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2efa0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2efb0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2efc0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2efd0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2efe0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2eff0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2f000 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2f010 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2f020 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2f030 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2f040 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2f050 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2f060 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2f070 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2f080 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2f090 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2f0a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2f0b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f0c0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2f0d0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2f0e0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2f0f0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2f100 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2f110 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2f120 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2f130 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2f140 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2f150 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2f160 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2f170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f180 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2f190 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2f1a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f1b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2f1c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f1d0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2f1e0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2f1f0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2f200 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2f210 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2f220 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2f230 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2f240 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2f250 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2f260 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2f270 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2f280 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2f290 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2f2a0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2f2b0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2f2c0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2f2d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2f2e0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2f2f0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2f300 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2f310 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2f320 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2f330 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2f340 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2f350 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2f360 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2f370 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2f380 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2f390 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2f3a0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2f3b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2f3c0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2f3d0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2f3e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2f3f0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2f400 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2f410 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2f420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2f430 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2f440 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2f450 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2f460 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2f470 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2f480 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2f490 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2f4a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2f4b0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2f4c0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2f4d0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2f4e0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2f4f0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2f500 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2f510 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2f520 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2f530 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2f540 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2f550 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2f560 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2f570 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2f580 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2f590 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2f5a0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2f5b0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2f5c0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2f5d0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2f5e0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2f5f0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2f600 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2f610 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2f620 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2f630 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2f640 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2f650 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2f660 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2f670 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2f680 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2f690 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f6a0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2f6b0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2f6c0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2f6d0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2f6e0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2f6f0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2f700 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2f710 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2f720 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2f730 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f740 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2f750 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2f760 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2f770 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2f780 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2f790 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2f7a0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2f7b0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2f7c0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2f7d0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2f7e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2f7f0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2f800 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2f810 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2f820 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2f830 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2f840 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2f850 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2f860 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2f870 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2f880 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2f890 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2f8a0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2f8b0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2f8c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f8d0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2f8e0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2f8f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2f900 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2f910 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2f920 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2f930 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2f940 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2f950 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2f960 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2f970 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2f980 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2f990 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2f9a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2f9b0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2f9c0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2f9d0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2f9e0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2f9f0 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2fa00 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2fa10 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2fa20 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2fa30 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2fa40 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2fa50 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2fa60 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2fa70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2fa80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fa90 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2faa0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2fab0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2fac0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2fad0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2fae0 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2faf0 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2fb00 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2fb10 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2fb20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2fb30 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2fb40 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2fb50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2fb60 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2fb70 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2fb80 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2fb90 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2fba0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fbb0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2fbc0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2fbd0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2fbe0 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2fbf0 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2fc00 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2fc10 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2fc20 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2fc30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2fc40 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2fc50 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2fc60 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2fc70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2fc80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fc90 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2fca0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2fcb0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2fcc0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2fcd0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2fce0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2fcf0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2fd00 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2fd10 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2fd20 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2fd30 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2fd40 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2fd50 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2fd60 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2fd70 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2fd80 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2fd90 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2fda0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2fdb0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2fdc0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2fdd0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2fde0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2fdf0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2fe00 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2fe10 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2fe20 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2fe30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2fe40 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2fe50 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2fe60 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2fe70 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2fe80 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2fe90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2fea0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2feb0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2fec0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2fed0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2fee0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2fef0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
2ff00 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2ff10 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2ff20 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2ff30 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2ff40 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2ff50 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2ff60 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2ff70 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2ff80 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2ff90 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2ffa0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
2ffb0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
2ffc0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
2ffd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ffe0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
2fff0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
30000 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30010 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
30020 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
30030 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
30040 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
30050 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
30060 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
30070 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30080 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
30090 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
300a0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
300b0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
300c0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
300d0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
300e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
300f0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
30100 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
30110 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
30120 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
30130 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
30140 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
30150 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
30160 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30170 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30180 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
30190 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
301a0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
301b0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
301c0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
301d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
301e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
301f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
30200 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30210 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
30220 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
30230 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
30240 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
30250 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
30260 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
30270 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30280 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30290 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
302a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
302b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
302c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
302d0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
302e0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
302f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30300 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
30310 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
30320 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
30330 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
30340 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
30350 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
30360 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
30370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30380 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30390 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
303a0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
303b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
303c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
303d0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
303e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
303f0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
30400 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
30410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
30420 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
30430 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
30440 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
30450 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
30460 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
30470 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
30480 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
30490 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
304a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
304b0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
304c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
304d0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
304e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
304f0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
30500 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30510 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
30520 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
30530 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
30540 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
30550 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
30560 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
30570 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
30580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
30590 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
305a0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
305b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
305c0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
305d0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
305e0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
305f0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
30600 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
30610 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
30620 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
30630 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
30640 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
30650 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
30660 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
30670 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
30680 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
30690 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
306a0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
306b0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
306c0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
306d0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
306e0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
306f0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
30700 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
30710 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
30720 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
30730 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
30740 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
30750 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
30760 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
30770 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30780 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30790 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
307a0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
307b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
307c0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
307d0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
307e0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
307f0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
30800 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
30810 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
30820 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
30830 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30840 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
30850 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
30860 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30870 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
30880 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
30890 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
308a0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
308b0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
308c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
308d0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
308e0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
308f0 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
30900 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
30910 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
30920 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
30930 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
30940 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
30950 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
30960 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
30970 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
30980 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30990 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
309a0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
309b0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
309c0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
309d0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
309e0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
309f0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
30a00 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
30a10 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
30a20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
30a30 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
30a40 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
30a50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30a60 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30a70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30a80 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
30a90 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
30aa0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
30ab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
30ac0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
30ad0 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
30ae0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
30af0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
30b00 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
30b10 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
30b20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30b30 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
30b40 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
30b50 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
30b60 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
30b70 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
30b80 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
30b90 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30ba0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
30bb0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
30bc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30bd0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
30be0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
30bf0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
30c00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30c10 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
30c20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
30c30 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
30c40 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
30c50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30c60 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
30c70 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
30c80 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
30c90 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
30ca0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
30cb0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
30cc0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
30cd0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
30ce0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
30cf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
30d00 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
30d10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30d20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
30d30 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
30d40 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
30d50 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
30d60 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
30d70 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
30d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
30d90 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
30da0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
30db0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
30dc0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
30dd0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
30de0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
30df0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
30e00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30e10 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
30e20 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
30e30 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
30e40 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
30e50 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
30e60 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
30e70 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
30e80 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
30e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
30ea0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
30eb0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30ec0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
30ed0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
30ee0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
30ef0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
30f00 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
30f10 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
30f20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
30f30 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
30f40 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
30f50 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
30f60 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
30f70 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
30f80 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
30f90 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
30fa0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
30fb0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
30fc0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
30fd0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
30fe0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
30ff0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
31000 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
31010 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
31020 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
31030 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
31040 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
31050 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
31060 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
31070 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
31080 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
31090 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
310a0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
310b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
310c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
310d0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
310e0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
310f0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
31100 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
31110 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
31120 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
31130 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
31140 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
31150 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
31160 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31170 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
31180 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31190 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
311a0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
311b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
311c0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
311d0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
311e0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
311f0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
31200 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
31210 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
31220 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
31230 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
31240 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31250 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31260 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31270 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31280 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
31290 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
312a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
312b0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
312c0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
312d0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
312e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
312f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
31300 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
31310 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31320 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
31330 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
31340 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
31350 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
31360 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
31370 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
31380 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31390 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
313a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
313b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
313c0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
313d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
313e0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
313f0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31400 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
31410 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
31430 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
31440 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
31450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
31460 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
31470 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
31480 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
31490 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
314a0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
314b0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
314c0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
314d0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
314e0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
314f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
31500 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
31510 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31520 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
31530 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
31540 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
31550 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31560 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
31570 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
31580 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
31590 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
315a0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
315b0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
315c0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
315d0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
315e0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
315f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31600 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
31610 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
31620 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
31630 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
31640 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
31650 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
31660 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31670 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
31680 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
31690 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
316a0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
316b0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
316c0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
316d0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
316e0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
316f0 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
31700 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
31710 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
31720 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
31730 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
31740 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
31750 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
31760 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
31770 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
31780 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
31790 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
317a0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
317b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
317c0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
317d0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
317e0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
317f0 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
31800 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
31810 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
31820 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
31830 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31840 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31850 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
31860 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
31870 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
31880 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
31890 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
318a0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
318b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
318c0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
318d0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
318e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
318f0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
31900 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
31910 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
31920 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
31930 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
31940 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
31950 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
31960 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
31970 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31980 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
31990 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
319a0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
319b0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
319c0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
319d0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
319e0 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
319f0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
31a00 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
31a10 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
31a20 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31a30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31a40 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
31a50 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
31a60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31a70 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
31a80 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
31a90 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
31aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
31ab0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
31ac0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31ad0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
31ae0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
31af0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
31b00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31b10 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
31b20 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
31b30 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
31b40 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
31b50 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
31b60 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
31b70 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
31b80 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
31b90 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
31ba0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
31bb0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
31bc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
31bd0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
31be0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
31bf0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
31c00 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
31c10 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
31c20 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31c30 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31c40 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31c50 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
31c60 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
31c70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31c80 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
31c90 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
31ca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
31cb0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
31cc0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
31cd0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
31ce0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
31cf0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
31d00 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
31d10 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
31d20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
31d30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
31d40 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
31d50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31d60 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
31d70 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
31d80 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
31d90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
31da0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
31db0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
31dc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
31dd0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
31de0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
31df0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31e00 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31e10 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
31e20 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
31e30 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
31e40 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
31e50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
31e60 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
31e70 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
31e80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31e90 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
31ea0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
31eb0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
31ec0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
31ed0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
31ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
31ef0 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
31f00 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
31f10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31f20 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
31f30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31f40 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
31f50 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
31f60 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
31f70 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
31f80 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
31f90 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
31fa0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
31fb0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
31fc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
31fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31fe0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
31ff0 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
32000 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
32010 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
32020 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
32030 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
32040 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
32050 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
32060 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
32070 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
32080 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
32090 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
320a0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
320b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
320c0 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
320d0 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
320e0 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
320f0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
32100 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
32110 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
32120 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
32130 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
32140 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
32150 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
32160 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
32170 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
32180 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
32190 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
321a0 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
321b0 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
321c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
321d0 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
321e0 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
321f0 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
32200 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
32210 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
32220 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
32230 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
32240 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
32250 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
32260 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
32270 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
32280 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
32290 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
322a0 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
322b0 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
322c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
322d0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
322e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
322f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
32300 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
32310 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
32320 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
32330 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
32340 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
32350 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
32360 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
32370 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32380 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65  ction. ^If no me
32390 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
323a0 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
323b0 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
323c0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
323d0 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
323e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
323f0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
32400 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
32410 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
32420 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
32430 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
32440 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
32450 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
32460 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32470 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32480 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
32490 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
324a0 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
324b0 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
324c0 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
324d0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
324e0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
324f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32500 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32510 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
32520 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
32530 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32540 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
32550 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
32560 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
32570 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66  estroyed..** ^If
32580 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
32590 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
325a0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
325b0 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
325c0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
325d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
325e0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
325f0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
32600 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
32610 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
32620 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
32630 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
32640 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
32650 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
32660 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
32670 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
32680 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
32690 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
326a0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
326b0 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
326c0 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
326d0 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
326e0 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79  time.  ^The only
326f0 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
32700 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
32710 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
32720 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
32730 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
32740 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
32750 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
32760 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
32770 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
32780 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
32790 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
327a0 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
327b0 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
327c0 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
327d0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
327e0 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a  [parameters].)^.
327f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32800 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
32810 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
32820 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
32830 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
32840 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32850 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
32860 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
32870 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32880 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
32890 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
328a0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
328b0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
328c0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
328d0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
328e0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
328f0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
32900 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
32910 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
32920 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
32930 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
32940 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
32950 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
32960 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
32970 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
32980 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
32990 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
329a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
329b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
329c0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
329d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
329e0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
329f0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
32a00 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
32a10 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
32a20 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
32a30 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
32a40 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
32a50 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
32a60 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
32a70 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
32a80 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
32a90 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
32aa0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
32ab0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
32ac0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
32ad0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
32ae0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
32af0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
32b00 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
32b10 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
32b20 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
32b30 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
32b40 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
32b50 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
32b60 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
32b70 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
32b80 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
32b90 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
32ba0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
32bb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
32bc0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
32bd0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
32be0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
32bf0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
32c00 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
32c10 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
32c20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
32c30 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
32c40 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
32c50 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
32c60 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
32c70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
32c80 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
32c90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
32ca0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
32cb0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
32cc0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32cd0 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
32ce0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
32cf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32d00 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
32d10 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
32d20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
32d30 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
32d40 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
32d50 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
32d60 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
32d70 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
32d80 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
32d90 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
32da0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
32db0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
32dc0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
32dd0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
32de0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32df0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
32e00 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
32e10 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
32e20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32e30 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
32e40 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
32e50 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
32e60 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
32e70 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
32e80 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
32e90 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
32ea0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
32eb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
32ec0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32ed0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
32ee0 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
32ef0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
32f00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32f10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32f20 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
32f30 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
32f40 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
32f50 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
32f60 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
32f70 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
32f80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
32f90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32fa0 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
32fb0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
32fc0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
32fd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32fe0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32ff0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
33000 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
33010 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
33020 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
33030 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33040 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33050 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33060 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
33070 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
33080 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
33090 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
330a0 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
330b0 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
330c0 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
330d0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
330e0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
330f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
33100 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
33110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33120 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
33130 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
33140 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
33150 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
33160 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
33170 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
33180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33190 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
331a0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
331b0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
331c0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
331d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
331e0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
331f0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
33200 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
33210 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
33220 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33230 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
33240 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33250 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
33260 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
33270 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
33280 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
33290 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
332a0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
332b0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
332c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
332d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
332e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
332f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
33300 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
33310 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
33320 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
33330 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
33340 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
33350 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
33360 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
33370 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
33380 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33390 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
333a0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
333b0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
333c0 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
333d0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
333e0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
333f0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
33400 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
33410 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
33420 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
33430 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
33440 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
33450 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
33460 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
33470 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33480 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
33490 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
334a0 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
334b0 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
334c0 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
334d0 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
334e0 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
334f0 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
33500 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
33510 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
33520 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
33530 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
33540 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
33550 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
33560 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
33570 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
33580 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
33590 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
335a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
335b0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
335c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
335d0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
335e0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
335f0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
33600 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
33610 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
33620 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
33630 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33640 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
33650 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
33660 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
33670 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
33680 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
33690 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
336a0 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
336b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
336c0 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
336d0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
336e0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
336f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33700 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33710 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
33720 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
33730 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
33740 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
33750 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33760 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
33770 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
33780 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
33790 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
337a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
337b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
337c0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
337d0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
337e0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
337f0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
33800 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33810 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
33820 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33830 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33840 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33850 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33860 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
33870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33880 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
33890 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
338a0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
338b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
338c0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
338d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
338e0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
338f0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
33900 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
33910 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33920 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33930 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
33940 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
33950 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
33960 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
33970 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
33980 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
33990 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
339a0 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
339b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
339c0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
339d0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
339e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
339f0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
33a00 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
33a10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33a20 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
33a30 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
33a40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
33a50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33a60 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33a70 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
33a80 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
33a90 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
33aa0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
33ab0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
33ac0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
33ad0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
33ae0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
33af0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
33b00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33b10 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
33b20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
33b30 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
33b40 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
33b50 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
33b60 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
33b70 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
33b80 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
33b90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33ba0 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
33bb0 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
33bc0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
33bd0 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
33be0 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
33bf0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
33c00 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
33c10 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
33c20 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
33c30 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
33c40 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
33c50 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
33c60 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
33c70 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
33c80 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
33c90 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
33ca0 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
33cb0 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
33cc0 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
33cd0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
33ce0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
33cf0 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
33d00 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
33d10 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
33d20 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
33d30 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
33d40 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
33d50 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
33d60 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
33d70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
33d80 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
33d90 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
33da0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
33db0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
33dc0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
33dd0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
33de0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
33df0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
33e00 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
33e10 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
33e20 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
33e30 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
33e40 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
33e50 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
33e60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33e70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33e80 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
33e90 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
33ea0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
33eb0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
33ec0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
33ed0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
33ee0 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
33ef0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
33f00 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
33f10 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
33f20 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
33f30 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
33f40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
33f50 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
33f60 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
33f70 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
33f80 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
33f90 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
33fa0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
33fb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
33fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33fd0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
33fe0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
33ff0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
34000 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
34010 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
34020 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
34030 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
34040 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
34050 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
34060 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
34070 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
34080 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
34090 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
340a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
340b0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
340c0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
340d0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
340e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
340f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
34100 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
34110 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34120 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
34130 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
34140 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
34150 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
34160 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
34170 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
34180 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
34190 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
341a0 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
341b0 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
341c0 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
341d0 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
341e0 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
341f0 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
34200 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34210 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
34220 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
34230 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34240 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
34250 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
34260 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
34270 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
34280 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34290 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
342a0 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
342b0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
342c0 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
342d0 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
342e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
342f0 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
34300 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
34310 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
34320 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
34330 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
34340 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
34350 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34360 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
34370 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
34380 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
34390 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
343a0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
343b0 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
343c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
343d0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
343e0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
343f0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
34400 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
34410 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
34420 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
34430 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
34440 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34450 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
34460 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
34470 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
34480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34490 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
344a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
344b0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
344c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
344d0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
344e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
344f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34500 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
34510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34520 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
34530 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
34540 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
34550 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
34560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
34570 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
34580 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
34590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
345a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
345b0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
345c0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
345d0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
345e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
345f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34600 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
34610 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34620 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
34630 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
34640 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34650 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
34660 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34670 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
34680 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
34690 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
346a0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
346b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
346c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
346d0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
346e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
346f0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
34700 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34710 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
34720 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
34730 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34740 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
34750 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
34760 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34770 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34780 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
34790 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
347a0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
347b0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
347c0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
347d0 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
347e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
347f0 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
34800 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
34810 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
34820 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
34830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34840 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
34850 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
34860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
34870 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
34880 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
34890 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
348a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
348b0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
348c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
348d0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
348e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
348f0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
34900 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
34910 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34920 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
34930 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
34940 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
34950 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
34960 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
34970 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
34980 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
34990 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
349a0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
349b0 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
349c0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
349d0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
349e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
349f0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
34a00 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
34a10 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
34a20 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
34a30 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
34a40 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
34a50 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
34a60 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
34a70 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
34a80 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
34a90 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
34aa0 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
34ab0 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
34ac0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34ad0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
34ae0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
34af0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
34b00 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
34b10 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
34b20 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
34b30 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
34b40 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
34b50 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34b60 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
34b70 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
34b80 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
34b90 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
34ba0 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
34bb0 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
34bc0 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
34bd0 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
34be0 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
34bf0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
34c00 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
34c10 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
34c20 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
34c30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
34c40 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
34c50 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
34c60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
34c70 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
34c80 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
34c90 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
34ca0 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
34cb0 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
34cc0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
34cd0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
34ce0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
34cf0 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
34d00 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
34d10 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
34d20 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
34d30 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
34d40 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
34d50 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
34d60 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
34d70 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
34d80 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
34d90 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
34da0 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
34db0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
34dc0 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
34dd0 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
34de0 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
34df0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
34e00 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
34e10 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
34e20 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
34e30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
34e40 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34e60 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
34e70 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
34e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34e90 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
34ea0 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
34eb0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
34ec0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
34ed0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
34ee0 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
34ef0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
34f00 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
34f10 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
34f20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
34f30 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
34f40 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
34f50 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
34f60 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
34f70 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
34f80 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
34f90 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
34fa0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
34fb0 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
34fc0 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
34fd0 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
34fe0 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
34ff0 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
35000 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
35010 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
35020 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
35030 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
35040 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
35050 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
35060 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
35070 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
35080 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
35090 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
350a0 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
350b0 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
350c0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
350d0 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
350e0 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
350f0 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
35100 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
35110 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
35120 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
35130 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
35140 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
35150 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
35160 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
35170 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
35180 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
35190 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
351a0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
351b0 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
351c0 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
351d0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
351e0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
351f0 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
35200 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
35210 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
35220 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35230 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
35240 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
35250 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35260 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35270 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
35280 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
35290 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
352a0 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
352b0 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
352c0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
352d0 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
352e0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
352f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
35300 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
35310 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35320 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
35330 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
35340 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
35350 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
35360 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
35370 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
35380 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
35390 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
353a0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
353b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
353c0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
353d0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
353e0 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
353f0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
35400 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
35410 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
35420 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
35430 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
35440 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
35450 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35460 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
35470 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
35480 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
35490 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
354a0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
354b0 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
354c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
354d0 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
354e0 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
354f0 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
35500 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
35510 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
35520 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
35530 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
35540 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
35550 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
35560 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
35570 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
35580 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
35590 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
355a0 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
355b0 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
355c0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
355d0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
355e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
355f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
35600 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35610 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
35620 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35630 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
35640 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
35650 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
35660 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
35670 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
35680 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
35690 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
356a0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
356b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
356c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
356d0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
356e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
356f0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
35700 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
35710 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
35720 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
35730 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
35740 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
35750 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
35760 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
35770 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35780 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
35790 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
357a0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
357b0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
357c0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
357d0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
357e0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
357f0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35800 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
35810 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
35820 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
35830 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
35840 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
35850 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
35860 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
35870 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
35880 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
35890 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
358a0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
358b0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
358c0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
358d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
358e0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
358f0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
35900 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
35910 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
35920 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
35930 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
35940 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
35950 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
35960 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
35970 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
35980 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
35990 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
359a0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
359b0 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
359c0 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
359d0 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
359e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
359f0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
35a00 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
35a10 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
35a20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
35a30 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
35a40 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
35a50 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
35a60 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
35a70 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
35a80 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
35a90 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
35aa0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
35ab0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
35ac0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
35ad0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
35ae0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
35af0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
35b00 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
35b10 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
35b20 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35b30 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
35b40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
35b50 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
35b60 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
35b70 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
35b80 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
35b90 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
35ba0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
35bb0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
35bc0 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
35bd0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
35be0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35bf0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
35c00 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
35c10 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
35c20 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
35c30 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
35c40 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
35c50 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
35c60 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
35c70 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
35c80 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
35c90 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
35ca0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
35cb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35cc0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
35cd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
35ce0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
35cf0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35d00 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
35d10 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
35d20 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
35d30 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
35d40 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
35d50 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
35d60 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
35d70 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
35d80 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35d90 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
35da0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
35db0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
35dc0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
35dd0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
35de0 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
35df0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
35e00 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
35e10 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
35e20 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
35e30 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
35e40 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
35e50 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
35e60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
35e70 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
35e80 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
35e90 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
35ea0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
35eb0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
35ec0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
35ed0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
35ee0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
35ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35f00 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
35f10 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
35f20 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
35f30 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
35f40 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  e key */.);.int 
35f50 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a  sqlite3_key_v2(.
35f60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
35f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35f80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
35f90 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
35fa0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
35fb0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
35fc0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
35fd0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
35fe0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
35ff0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
36000 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
36010 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
36020 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
36030 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
36040 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
36050 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
36060 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
36070 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
36080 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
36090 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
360a0 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
360b0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
360c0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
360d0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
360e0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
360f0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
36100 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
36110 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
36120 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
36130 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
36140 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
36150 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
36160 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
36170 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
36180 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
36190 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  ew key */.);.int
361a0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
361b0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
361c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
361d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
361e0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
361f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36200 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
36210 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
36220 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
36230 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
36240 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
36250 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
36260 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
36270 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
36280 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
36290 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
362a0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
362b0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
362c0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
362d0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
362e0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
362f0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
36300 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
36310 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
36320 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
36330 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
36340 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
36350 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
36360 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
36370 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
36380 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
36390 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
363a0 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
363b0 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
363c0 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
363d0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
363e0 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
363f0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
36400 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
36410 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
36420 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
36430 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
36440 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
36450 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
36460 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
36470 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
36480 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
36490 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
364a0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
364b0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
364c0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
364d0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
364e0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
364f0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
36500 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
36510 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
36520 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
36530 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
36540 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
36550 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
36560 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
36570 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
36580 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
36590 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
365a0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
365b0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
365c0 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
365d0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
365e0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
365f0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
36600 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
36610 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
36620 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
36630 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
36640 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
36650 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
36660 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
36670 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
36680 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
36690 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
366a0 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
366b0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
366c0 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
366d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
366e0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
366f0 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
36700 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
36710 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
36720 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
36730 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
36740 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
36750 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
36760 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
36770 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
36780 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
36790 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
367a0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
367b0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
367c0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
367d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
367e0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
367f0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
36800 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
36810 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
36820 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
36830 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
36840 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
36850 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
36860 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
36870 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
36880 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
36890 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
368a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
368b0 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
368c0 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
368d0 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
368e0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
368f0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
36900 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36910 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36920 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
36930 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
36940 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
36950 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
36960 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
36970 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
36980 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
36990 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
369a0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
369b0 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
369c0 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
369d0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
369e0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
369f0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
36a00 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
36a10 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
36a20 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
36a30 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
36a40 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
36a50 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
36a60 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
36a70 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
36a80 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
36a90 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
36aa0 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
36ab0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36ac0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
36ad0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
36ae0 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
36af0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
36b00 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
36b10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
36b20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
36b30 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
36b40 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36b50 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
36b60 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
36b70 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
36b80 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
36b90 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
36ba0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
36bb0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
36bc0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
36bd0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
36be0 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
36bf0 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
36c00 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
36c10 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
36c20 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
36c30 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
36c40 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
36c50 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
36c60 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
36c70 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
36c80 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
36c90 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
36ca0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
36cb0 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
36cc0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36cd0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
36ce0 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ided..**.** <b>N
36cf0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
36d00 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
36d10 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
36d20 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
36d30 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
36d40 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  to calling [sqli
36d50 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71  te3_open] or [sq
36d60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20  lite3_open_v2]. 
36d70 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
36d80 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
36d90 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
36da0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
36db0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
36dc0 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a  .  Here is an.**
36dd0 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20   example of how 
36de0 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67  to do this using
36df0 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69   C++ with the Wi
36e00 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a  ndows Runtime:.*
36e10 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
36e20 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54  ><pre>.** LPCWST
36e30 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77  R zPath = Window
36e40 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c  s::Storage::Appl
36e50 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72  icationData::Cur
36e60 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b  rent->.** &nbsp;
36e70 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f       TemporaryFo
36e80 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61  lder->Path->Data
36e90 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74  ();.** char zPat
36ea0 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54  hBuf&#91;MAX_PAT
36eb0 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d  H + 1&#93;;.** m
36ec0 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20  emset(zPathBuf, 
36ed0 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  0, sizeof(zPathB
36ee0 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61  uf));.** WideCha
36ef0 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f  rToMultiByte(CP_
36f00 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20  UTF8, 0, zPath, 
36f10 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69  -1, zPathBuf, si
36f20 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a  zeof(zPathBuf),.
36f30 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55  ** &nbsp;     NU
36f40 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71  LL, NULL);.** sq
36f50 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
36f60 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d  tory = sqlite3_m
36f70 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61  printf("%s", zPa
36f80 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65  thBuf);.** </pre
36f90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
36fa0 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
36fb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
36fc0 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
36fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
36fe0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
36ff0 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
37000 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
37010 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
37020 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
37030 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
37040 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
37050 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
37060 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
37070 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
37080 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
37090 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
370a0 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
370b0 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
370c0 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
370d0 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
370e0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
370f0 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
37100 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
37110 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
37120 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
37130 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
37140 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
37150 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
37160 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
37170 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
37180 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
37190 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
371a0 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
371b0 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
371c0 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
371d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
371e0 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
371f0 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
37200 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
37210 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
37220 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
37230 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
37240 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
37250 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
37260 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
37270 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
37280 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
37290 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
372a0 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
372b0 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
372c0 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
372d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
372e0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
372f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
37300 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
37310 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
37320 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
37330 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
37340 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37350 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
37360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37370 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
37380 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
37390 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
373a0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
373b0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
373c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
373d0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
373e0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
373f0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
37400 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
37410 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
37420 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
37430 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
37440 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
37450 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
37460 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
37470 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
37480 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37490 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
374a0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
374b0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
374c0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
374d0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
374e0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
374f0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
37500 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
37510 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37520 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
37530 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
37540 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
37550 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
37560 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
37570 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
37580 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
37590 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
375a0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
375b0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
375c0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
375d0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
375e0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
375f0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
37600 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
37610 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
37620 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
37630 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
37640 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
37650 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
37660 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
37670 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
37680 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
37690 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
376a0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
376b0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
376c0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
376d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
376e0 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
376f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37700 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
37710 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
37720 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
37730 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
37740 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
37750 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
37760 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
37770 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
37780 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
37790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
377a0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
377b0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
377c0 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
377d0 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
377e0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
377f0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
37800 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
37810 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
37820 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
37830 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
37840 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
37850 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
37860 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
37870 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
37880 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
37890 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
378a0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
378b0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
378c0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
378d0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
378e0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
378f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
37900 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
37910 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
37920 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
37930 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
37940 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
37950 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
37960 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
37970 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
37980 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
37990 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
379a0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
379b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
379c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
379d0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
379e0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
379f0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
37a00 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
37a10 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
37a20 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
37a30 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
37a40 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
37a50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
37a60 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
37a70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
37a80 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
37a90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37aa0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
37ab0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
37ac0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
37ad0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
37ae0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
37af0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
37b00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
37b10 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
37b20 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
37b30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37b40 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
37b50 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
37b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
37b70 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
37b80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37b90 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
37ba0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
37bb0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
37bc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37bd0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
37be0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
37bf0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
37c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
37c10 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
37c20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
37c30 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
37c40 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
37c50 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
37c60 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
37c70 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
37c80 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
37c90 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
37ca0 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
37cb0 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f   The Filename Fo
37cc0 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  r A Database Con
37cd0 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
37ce0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  he sqlite3_db_fi
37cf0 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65  lename(D,N) inte
37d00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37d10 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c  pointer to a fil
37d20 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61  ename.** associa
37d30 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
37d40 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  e N of connectio
37d50 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20  n D.  ^The main 
37d60 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
37d70 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d   has the name "m
37d80 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20  ain".  If there 
37d90 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64  is no attached d
37da0 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65  atabase N on the
37db0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37dc0 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66  nection D, or if
37dd0 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61   database N is a
37de0 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e   temporary or in
37df0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
37e00 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c  , then.** a NULL
37e10 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
37e20 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
37e30 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e   filename return
37e40 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
37e50 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75  ion is the outpu
37e60 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c  t of the.** xFul
37e70 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64  lPathname method
37e80 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20   of the [VFS].  
37e90 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  ^In other words,
37ea0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
37eb0 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f   will be an abso
37ec0 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65  lute pathname, e
37ed0 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e  ven if the filen
37ee0 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f  ame used.** to o
37ef0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
37f00 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20   originally was 
37f10 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76  a URI or relativ
37f20 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63  e pathname..*/.c
37f30 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
37f40 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73  e3_db_filename(s
37f50 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
37f60 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
37f70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37f80 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20  F: Determine if 
37f90 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  a database is re
37fa0 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  ad-only.**.** ^T
37fb0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  he sqlite3_db_re
37fc0 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65  adonly(D,N) inte
37fd0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20  rface returns 1 
37fe0 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
37ff0 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69  N.** of connecti
38000 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c  on D is read-onl
38010 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65  y, 0 if it is re
38020 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20  ad/write, or -1 
38030 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  if N is not.** t
38040 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74  he name of a dat
38050 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74  abase on connect
38060 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ion D..*/.int sq
38070 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
38080 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
38090 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
380a0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
380b0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
380c0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
380d0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
380e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
380f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
38100 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
38110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
38120 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
38130 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
38140 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
38150 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
38160 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
38170 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
38180 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38190 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
381a0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
381b0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
381c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
381d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
381e0 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
381f0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
38200 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
38210 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
38220 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
38230 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
38240 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
38250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38260 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
38270 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
38280 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
38290 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
382a0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
382b0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
382c0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
382d0 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
382e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
382f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
38300 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
38310 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
38320 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
38330 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
38340 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
38350 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
38360 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
38370 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
38380 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
38390 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
383a0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
383b0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
383c0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
383d0 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
383e0 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
383f0 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
38400 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
38410 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
38420 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
38430 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
38440 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
38450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38460 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
38470 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
38480 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
38490 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
384a0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
384b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
384c0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
384d0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
384e0 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
384f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
38500 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
38510 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
38520 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
38530 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
38540 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
38550 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
38560 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
38570 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
38580 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
38590 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
385a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
385b0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
385c0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
385d0 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
385e0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
385f0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
38600 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
38610 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
38620 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38630 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
38640 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
38650 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
38660 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
38670 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
38680 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
38690 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
386a0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
386b0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
386c0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
386d0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
386e0 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
386f0 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
38700 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
38710 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d  D..**.** The com
38720 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b  mit and rollback
38730 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20   hook callbacks 
38740 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e  are not reentran
38750 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
38760 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
38770 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
38780 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
38790 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
387a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
387b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
387c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
387d0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
387e0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
387f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38800 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
38810 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
38820 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
38830 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5