/ Hex Artifact Content
Login

Artifact e08f84145c049bef7a235221f1b5dc65a79db9ad:


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 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
7c30: 74 20 28 2a 78 4d 61 70 29 28 73 71 6c 69 74 65  t (*xMap)(sqlite
7c40: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7c50: 5f 69 6e 74 36 34 20 6f 66 73 74 2c 20 73 71 6c  _int64 ofst, sql
7c60: 69 74 65 33 5f 69 6e 74 36 34 20 6c 65 6e 2c 0a  ite3_int64 len,.
7c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
7c80: 74 20 6d 6d 61 70 46 6c 61 67 73 2c 20 76 6f 69  t mmapFlags, voi
7c90: 64 20 2a 2a 70 70 4d 65 6d 4f 62 6a 2c 20 76 6f  d **ppMemObj, vo
7ca0: 69 64 20 2a 2a 70 70 4d 65 6d 29 3b 0a 20 20 69  id **ppMem);.  i
7cb0: 6e 74 20 28 2a 78 55 6e 6d 61 70 29 28 73 71 6c  nt (*xUnmap)(sql
7cc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7cd0: 20 2a 70 4d 65 6d 4f 62 6a 29 3b 0a 20 20 2f 2a   *pMemObj);.  /*
7ce0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
7cf0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
7d00: 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41  sion 3 */.  /* A
7d10: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
7d20: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
7d30: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
7d40: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
7d50: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
7d60: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
7d70: 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  pcodes.**.** The
7d80: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
7d90: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
7da0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
7db0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
7dc0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
7dd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7de0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
7df0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7e00: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
7e10: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
7e20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
7e30: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
7e40: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
7e50: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
7e60: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
7e70: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7e80: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
7e90: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
7ea0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
7eb0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
7ec0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
7ed0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7ee0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
7ef0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
7f00: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7f10: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
7f20: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
7f30: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
7f40: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
7f50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
7f60: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
7f70: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
7f80: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
7f90: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
7fa0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
7fb0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
7fc0: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  * is defined..**
7fd0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
7fe0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
7ff0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8000: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8010: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8020: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8030: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8040: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8050: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8060: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8070: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8080: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8090: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
80a0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
80b0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
80c0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
80d0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
80e0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
80f0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8100: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8110: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8120: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8130: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8140: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8150: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  faster..**.** Th
8160: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8170: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
8180: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
8190: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
81a0: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
81b0: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
81c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
81d0: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
81e0: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
81f0: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
8200: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
8210: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
8220: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
8230: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
8240: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
8250: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
8260: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
8270: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
8280: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
8290: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
82a0: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
82b0: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
82c0: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
82d0: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
82e0: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
82f0: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
8300: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
8310: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
8320: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
8330: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
8340: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
8350: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
8360: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8370: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8390: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
83a0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
83b0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
83c0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
83d0: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
83e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
83f0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8400: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8410: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8420: 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  *.** ^(The [SQLI
8430: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8440: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73  ITTED] opcode is
8450: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
8460: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69  nally by.** SQLi
8470: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61  te and sent to a
8480: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63  ll VFSes in plac
8490: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74  e of a call to t
84a0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a  he xSync method.
84b0: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ** when the data
84c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
84d0: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  has [PRAGMA sync
84e0: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20  hronous] set to 
84f0: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73  OFF.)^.** Some s
8500: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
8510: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
8520: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70  l in order to op
8530: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a  erate correctly.
8540: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20  ** when [PRAGMA 
8550: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
8560: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8570: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75  =OFF] is set, bu
8580: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73  t most .** VFSes
8590: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
85a0: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f  s signal and sho
85b0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
85c0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
85d0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
85e0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
85f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8600: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
8610: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73  his.** opcode as
8620: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
8630: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
8640: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
8650: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20  alized VFSes.** 
8660: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
8670: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  it.  .**.** ^The
8680: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
8690: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
86a0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
86b0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
86c0: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
86d0: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
86e0: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
86f0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
8700: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
8710: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
8720: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74 6f 20  rder to work to 
8730: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
8740: 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20 61 6e  ss against.** an
8750: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
8760: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
8770: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
8780: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
8790: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
87a0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
87b0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
87c0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
87d0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
87e0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
87f0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
8800: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
8810: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
8820: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
8830: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
8840: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
8850: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
8860: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
8870: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
8880: 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73 20 28  hose to values (
8890: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
88a0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
88b0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
88c0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
88d0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
88e0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
88f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
8900: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
8910: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
8920: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
8930: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
8940: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
8950: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
8960: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
8970: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
8980: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
8990: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
89a0: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
89b0: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
89c0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
89d0: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
89e0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
89f0: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
8a00: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
8a10: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
8a20: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
8a30: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
8a40: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
8a50: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
8a60: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
8a70: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
8a80: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
8a90: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
8aa0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
8ac0: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
8ad0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
8ae0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
8af0: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
8b00: 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73 65 74  e AHead Log] set
8b10: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
8b20: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
8b30: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
8b40: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
8b50: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
8b60: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
8b70: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
8b80: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
8b90: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
8ba0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
8bb0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
8bc0: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
8bd0: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
8be0: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
8bf0: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
8c00: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
8c10: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
8c20: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
8c30: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
8c40: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
8c50: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
8c60: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
8c70: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
8c80: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
8c90: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8ca0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
8cb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8cc0: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
8cd0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
8ce0: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
8cf0: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
8d00: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
8d10: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
8d20: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
8d30: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
8d40: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8d50: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
8d60: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
8d70: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
8d80: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
8d90: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
8da0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
8db0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
8dc0: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
8dd0: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
8de0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
8df0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
8e00: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
8e10: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
8e20: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
8e30: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
8e40: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
8e50: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
8e60: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
8e70: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
8e80: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
8e90: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
8ea0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
8eb0: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
8ec0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
8ed0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
8ee0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
8ef0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
8f00: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
8f10: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
8f20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
8f30: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
8f40: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
8f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8f60: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8f70: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
8f80: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
8f90: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
8fa0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
8fb0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
8fc0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
8fd0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
8fe0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
8ff0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
9000: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
9010: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
9020: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
9030: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
9040: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
9050: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9060: 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e  TER     7.#defin
9070: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
9080: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
9090: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
90a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
90b0: 52 45 54 52 59 20 20 20 39 0a 23 64 65 66 69 6e  RETRY   9.#defin
90c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
90d0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 31  ERSIST_WAL     1
90e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
90f0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9100: 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
9110: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
9120: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
9130: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
9140: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
9150: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
9160: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
9170: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
9180: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
9190: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
91a0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
91b0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
91c0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
91d0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
91e0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
91f0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
9200: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
9210: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
9220: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
9230: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
9240: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
9250: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
9260: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
9270: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
9280: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
9290: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
92a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
92b0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
92c0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
92d0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
92e0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
92f0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
9300: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
9310: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
9320: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
9330: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
9340: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
9350: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
9360: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
9370: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
9380: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
9390: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
93a0: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
93b0: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
93c0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
93d0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
93e0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
93f0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
9400: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
9410: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
9420: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
9430: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
9440: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
9450: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
9460: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
9470: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
9480: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
9490: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
94a0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
94b0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
94c0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
94d0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
94e0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
94f0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
9500: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
9510: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
9520: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
9530: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
9540: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
9550: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
9560: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
9570: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
9580: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
9590: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
95a0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
95b0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
95c0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
95d0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
95e0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
95f0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
9600: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
9610: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
9620: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
9630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
9640: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
9650: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
9660: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
9670: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
9680: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
9690: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
96a0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
96b0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
96c0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
96d0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
96e0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
96f0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
9700: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
9710: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
9720: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
9730: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
9740: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
9750: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
9760: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
9770: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
9780: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
9790: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
97a0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
97b0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
97c0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
97d0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
97e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
97f0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
9800: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
9810: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
9820: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
9830: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
9840: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
9850: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
9860: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
9870: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
9880: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
9890: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
98a0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
98b0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
98c0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
98d0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
98e0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
98f0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
9900: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
9910: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
9920: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
9930: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
9940: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
9950: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
9960: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
9970: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
9980: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
9990: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
99a0: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
99b0: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
99c0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
99d0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
99e0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
99f0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
9a00: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
9a10: 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68   than.** 10 alph
9a20: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
9a30: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
9a40: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
9a50: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
9a60: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
9a70: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
9a80: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
9a90: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
9aa0: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
9ab0: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
9ac0: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
9ad0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9ae0: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
9af0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
9b00: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
9b10: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
9b20: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
9b30: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
9b40: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
9b50: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
9b60: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
9b70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
9b80: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
9b90: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
9ba0: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
9bb0: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
9bc0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
9bd0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
9be0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
9bf0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
9c00: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
9c10: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
9c20: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
9c30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
9c40: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
9c50: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
9c60: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
9c70: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
9c80: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
9c90: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
9ca0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
9cb0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
9cc0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
9cd0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
9ce0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
9cf0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
9d00: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
9d10: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
9d20: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
9d30: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
9d40: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
9d50: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
9d60: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
9d70: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
9d80: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
9d90: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
9da0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
9db0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
9dc0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
9dd0: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
9de0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
9df0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
9e00: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
9e10: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
9e20: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
9e30: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
9e40: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
9e50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9e60: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
9e70: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
9e80: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
9e90: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9ea0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
9eb0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9ec0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
9ed0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
9ee0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
9ef0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
9f00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
9f10: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
9f20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
9f30: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
9f40: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9f50: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
9f60: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
9f70: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
9f80: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
9f90: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
9fa0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
9fb0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
9fc0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
9fd0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
9fe0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
9ff0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
a000: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
a010: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
a020: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
a030: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
a040: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
a050: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
a060: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
a070: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
a080: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
a090: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
a0a0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
a0b0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
a0c0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
a0d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
a0e0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
a0f0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
a100: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
a110: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
a120: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
a130: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
a140: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
a150: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
a160: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
a170: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
a180: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
a190: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
a1a0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
a1b0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
a1c0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
a1d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
a1e0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
a1f0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
a200: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
a210: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
a220: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
a230: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
a240: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
a250: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
a260: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
a270: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
a280: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
a290: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
a2a0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
a2b0: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
a2c0: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
a2d0: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
a2e0: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
a2f0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
a300: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
a310: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
a320: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
a330: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
a340: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
a350: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
a360: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
a370: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
a380: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
a390: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
a3a0: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
a3b0: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
a3c0: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
a3d0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
a3e0: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
a3f0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
a400: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
a410: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
a420: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
a430: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
a440: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
a450: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
a460: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
a470: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
a480: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
a490: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
a4a0: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
a4b0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
a4c0: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
a4d0: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
a4e0: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
a4f0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
a500: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
a510: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
a520: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
a530: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
a540: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
a550: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
a560: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
a570: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
a580: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
a590: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
a5a0: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
a5b0: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
a5c0: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
a5d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
a5e0: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
a5f0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
a600: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
a610: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
a620: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a630: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
a640: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
a650: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
a660: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
a670: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
a680: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
a690: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
a6a0: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
a6b0: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
a6c0: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
a6d0: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
a6e0: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
a6f0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
a700: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
a710: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
a720: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
a730: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
a740: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
a750: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
a760: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
a770: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
a780: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
a790: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
a7a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a7b0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
a7c0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
a7d0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
a7e0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
a7f0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
a800: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
a810: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
a820: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
a830: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
a840: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
a850: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
a860: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
a870: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
a880: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
a890: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
a8a0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
a8b0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
a8c0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
a8d0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
a8e0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
a8f0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
a900: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
a910: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
a920: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
a930: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
a940: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
a950: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
a960: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
a970: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
a980: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
a990: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
a9a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
a9b0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
a9c0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
a9d0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
a9e0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
a9f0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
aa00: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
aa10: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
aa20: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
aa30: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
aa40: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
aa50: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
aa60: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
aa70: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
aa80: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
aa90: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
aaa0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
aab0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
aac0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
aad0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
aae0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
aaf0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
ab00: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
ab10: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
ab20: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
ab30: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
ab40: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
ab50: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
ab60: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
ab70: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
ab80: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
ab90: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
aba0: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
abb0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
abc0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
abd0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
abe0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
abf0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
ac00: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
ac10: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
ac20: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
ac30: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
ac40: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
ac50: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
ac60: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
ac70: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
ac80: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
ac90: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
aca0: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
acb0: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
acc0: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
acd0: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
ace0: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
acf0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
ad00: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
ad10: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
ad20: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
ad30: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
ad40: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
ad50: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
ad60: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
ad70: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
ad80: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
ad90: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
ada0: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
adb0: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
adc0: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
add0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
ade0: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
adf0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
ae00: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
ae10: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
ae20: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
ae30: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
ae40: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
ae50: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
ae60: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
ae70: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
ae80: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
ae90: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
aea0: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
aeb0: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
aec0: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
aed0: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
aee0: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
aef0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
af00: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
af10: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
af20: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
af30: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
af40: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
af50: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
af60: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
af70: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
af80: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
af90: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
afa0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
afb0: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
afc0: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
afd0: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
afe0: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
aff0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
b000: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
b010: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
b020: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
b030: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
b040: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
b050: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
b060: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
b070: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
b080: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
b090: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
b0a0: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
b0b0: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
b0c0: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
b0d0: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
b0e0: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
b0f0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
b100: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
b110: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
b120: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
b130: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
b140: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
b150: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
b160: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
b170: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
b180: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
b190: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
b1a0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
b1b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
b1c0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
b1d0: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
b1e0: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
b1f0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
b200: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
b210: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
b220: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
b230: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
b240: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
b250: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
b260: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
b270: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
b280: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
b290: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
b2a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
b2b0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
b2c0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
b2d0: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
b2e0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
b2f0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
b300: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
b310: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
b320: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
b330: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b340: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b350: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
b360: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
b370: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
b380: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
b390: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
b3a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
b3b0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
b3c0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
b3d0: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
b3e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
b3f0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
b400: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
b410: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
b420: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
b430: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
b440: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
b450: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
b460: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
b470: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
b480: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
b490: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
b4a0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
b4b0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
b4c0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
b4d0: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
b4e0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
b4f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
b500: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
b510: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
b520: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
b530: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
b540: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
b550: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
b560: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
b570: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
b580: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
b590: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
b5a0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
b5b0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
b5c0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
b5d0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
b5e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
b5f0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
b600: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
b610: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
b620: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
b630: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
b640: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
b650: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
b660: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
b670: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
b680: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
b690: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
b6a0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
b6b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
b6c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
b6d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
b6e0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
b6f0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
b700: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
b710: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
b720: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
b730: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
b740: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
b750: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
b760: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
b770: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
b780: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
b790: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
b7a0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
b7b0: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
b7c0: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
b7d0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
b7e0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
b7f0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
b800: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
b810: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
b820: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
b830: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
b840: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
b850: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
b860: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
b870: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
b880: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
b890: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
b8a0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
b8b0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
b8c0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
b8d0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
b8e0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
b8f0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
b900: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
b910: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
b920: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
b930: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
b940: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
b950: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
b960: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
b970: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
b980: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
b990: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
b9a0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
b9b0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
b9c0: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
b9d0: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
b9e0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
b9f0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
ba00: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
ba10: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
ba20: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
ba30: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
ba40: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
ba50: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
ba60: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
ba70: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
ba80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ba90: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
baa0: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
bab0: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
bac0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
bad0: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
bae0: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
baf0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
bb00: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
bb10: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
bb20: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
bb30: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
bb40: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
bb50: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
bb60: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
bb70: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
bb80: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
bb90: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
bba0: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
bbb0: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
bbc0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
bbd0: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
bbe0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
bbf0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
bc00: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
bc10: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
bc20: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
bc30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
bc40: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
bc50: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
bc60: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
bc70: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
bc80: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
bc90: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
bca0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bcb0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
bcc0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
bcd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
bce0: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
bcf0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
bd00: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
bd10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bd20: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
bd30: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
bd40: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
bd50: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
bd60: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
bd70: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
bd80: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
bd90: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
bda0: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
bdb0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
bdc0: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
bdd0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
bde0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
bdf0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
be00: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
be10: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
be20: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
be30: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
be40: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
be50: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
be60: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
be70: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
be80: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
be90: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
bea0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
beb0: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
bec0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
bed0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
bee0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
bef0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
bf00: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
bf10: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
bf20: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
bf30: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
bf40: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
bf50: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
bf60: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
bf70: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
bf80: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
bf90: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
bfa0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
bfb0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
bfc0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
bfd0: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
bfe0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
bff0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
c000: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
c010: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
c020: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
c030: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
c040: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
c050: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
c060: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
c070: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
c080: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
c090: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
c0a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
c0b0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
c0c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c0d0: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
c0e0: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
c0f0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
c100: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
c110: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
c120: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
c130: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
c140: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
c150: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
c160: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
c170: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
c180: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
c190: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
c1a0: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
c1b0: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
c1c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c1d0: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
c1e0: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
c1f0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
c200: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
c210: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
c220: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c230: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
c240: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
c250: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
c260: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
c270: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
c280: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
c290: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
c2a0: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
c2b0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
c2c0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
c2d0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
c2e0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
c2f0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
c300: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
c310: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
c320: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
c330: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
c340: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
c350: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
c360: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
c370: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
c380: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
c390: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
c3a0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
c3b0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
c3c0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
c3d0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
c3e0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
c3f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
c400: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
c410: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
c420: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
c430: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
c440: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
c450: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c460: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
c470: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
c480: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
c490: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
c4a0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
c4b0: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
c4c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
c4d0: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
c4e0: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
c4f0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
c500: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
c510: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
c520: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c530: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
c540: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
c550: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
c560: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c570: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
c580: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
c590: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
c5a0: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
c5b0: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
c5c0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c5d0: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
c5e0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
c5f0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
c600: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
c610: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
c620: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
c630: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
c640: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c650: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
c660: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
c670: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c680: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
c690: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
c6a0: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
c6b0: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
c6c0: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
c6d0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
c6e0: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
c6f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
c700: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
c710: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
c720: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
c730: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
c740: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
c750: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
c760: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
c770: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
c780: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
c790: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
c7a0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
c7b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
c7c0: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
c7d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
c7e0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
c7f0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
c800: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
c810: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
c820: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
c830: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
c840: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
c850: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
c860: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c870: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
c880: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
c890: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
c8a0: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
c8b0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
c8c0: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
c8d0: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
c8e0: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
c8f0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
c900: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
c910: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
c920: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c930: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
c940: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
c950: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
c960: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
c970: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
c980: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
c990: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
c9a0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
c9b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c9c0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
c9d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
c9e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
c9f0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
ca00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
ca10: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
ca20: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
ca30: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
ca40: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
ca50: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
ca60: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
ca70: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
ca80: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
ca90: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
caa0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
cab0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
cac0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
cad0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
cae0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
caf0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
cb00: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
cb10: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
cb20: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
cb30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
cb40: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
cb50: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
cb60: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
cb70: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
cb80: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
cb90: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
cba0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
cbb0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
cbc0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
cbd0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
cbe0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
cbf0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
cc00: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
cc10: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
cc20: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
cc30: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
cc40: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
cc50: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
cc60: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
cc70: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
cc80: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
cc90: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
cca0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
ccb0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
ccc0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
ccd0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
cce0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
ccf0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
cd00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
cd10: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
cd20: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
cd30: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
cd40: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
cd50: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
cd60: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
cd70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
cd80: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
cd90: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
cda0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
cdb0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
cdc0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
cdd0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
cde0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
cdf0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
ce00: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
ce10: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
ce20: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
ce30: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
ce40: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
ce50: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
ce60: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
ce70: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
ce80: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
ce90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
cea0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
ceb0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
cec0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
ced0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
cee0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
cef0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
cf00: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
cf10: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
cf20: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
cf30: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
cf40: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
cf50: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
cf60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
cf70: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
cf80: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
cf90: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
cfa0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
cfb0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
cfc0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
cfd0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
cfe0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
cff0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
d000: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
d010: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
d020: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d030: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
d040: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
d050: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
d060: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
d070: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
d080: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
d090: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
d0a0: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
d0b0: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
d0c0: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
d0d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
d0e0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
d0f0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
d100: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
d110: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
d120: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
d130: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
d140: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
d150: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
d160: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
d170: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
d180: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
d190: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
d1a0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
d1b0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
d1c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
d1d0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
d1e0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
d1f0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
d200: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
d210: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d220: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
d230: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d240: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
d250: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
d260: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
d270: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
d280: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d290: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
d2a0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
d2b0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
d2c0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
d2d0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
d2e0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
d2f0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
d300: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
d310: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
d320: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
d330: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
d340: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
d350: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
d360: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
d370: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
d380: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
d390: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
d3a0: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
d3b0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
d3c0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
d3d0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
d3e0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
d3f0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
d400: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
d410: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d420: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
d430: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
d440: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
d450: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
d460: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
d470: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
d480: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
d490: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
d4a0: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
d4b0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
d4c0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
d4d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
d4e0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
d4f0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
d500: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
d510: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
d520: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d530: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
d540: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
d550: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
d560: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
d570: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
d580: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
d590: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
d5a0: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
d5b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d5c0: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
d5d0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
d5e0: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
d5f0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
d600: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
d610: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
d620: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
d630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
d640: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
d650: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
d660: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
d670: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
d680: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
d690: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
d6a0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
d6b0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d6c0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
d6d0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
d6e0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
d6f0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
d700: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
d710: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
d720: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d730: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
d740: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
d750: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d760: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
d770: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d780: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
d790: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
d7a0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
d7b0: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
d7c0: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
d7d0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
d7e0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
d7f0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
d800: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
d810: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
d820: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
d830: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
d840: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
d850: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
d860: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
d870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
d880: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
d890: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
d8a0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
d8b0: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
d8c0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
d8d0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
d8e0: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
d8f0: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
d900: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
d910: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
d920: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
d930: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
d940: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
d950: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d960: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
d970: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d980: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
d990: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
d9a0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
d9b0: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
d9c0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
d9d0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
d9e0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
d9f0: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
da00: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
da10: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
da20: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
da30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
da40: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
da50: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
da60: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
da70: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
da80: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
da90: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
daa0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
dab0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
dac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
dad0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
dae0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
daf0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
db00: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
db10: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
db20: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
db30: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
db40: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
db50: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
db60: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
db70: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
db80: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
db90: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
dba0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
dbb0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
dbc0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
dbd0: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
dbe0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
dbf0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
dc00: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
dc10: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
dc20: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
dc30: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
dc40: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
dc50: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
dc60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
dc70: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
dc80: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
dc90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
dca0: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
dcb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
dcc0: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
dcd0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
dce0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
dcf0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
dd00: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
dd10: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
dd20: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
dd30: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
dd40: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
dd50: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
dd60: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
dd70: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
dd80: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
dd90: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
dda0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
ddb0: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
ddc0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
ddd0: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
dde0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
ddf0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
de00: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
de10: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
de20: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
de30: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
de40: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
de50: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
de60: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
de70: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
de80: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
de90: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
dea0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
deb0: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
dec0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ded0: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
dee0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
def0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
df00: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
df10: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
df20: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
df30: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
df40: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
df50: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
df60: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
df70: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
df80: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
df90: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
dfa0: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
dfb0: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
dfc0: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
dfd0: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
dfe0: 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
dff0: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
e000: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
e010: 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
e020: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
e030: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
e040: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
e050: 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
e060: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
e070: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
e080: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
e090: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
e0a0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
e0b0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
e0c0: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
e0d0: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
e0e0: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
e0f0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
e100: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
e110: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
e120: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
e130: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
e140: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
e150: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
e160: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
e170: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
e180: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
e190: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
e1a0: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
e1b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
e1c0: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
e1d0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
e1e0: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
e1f0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
e200: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
e210: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
e220: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
e230: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
e240: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e250: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
e260: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
e270: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
e280: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
e290: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
e2a0: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
e2b0: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
e2c0: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
e2d0: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
e2e0: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
e2f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
e300: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
e310: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
e320: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
e330: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
e340: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
e350: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
e360: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
e370: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e380: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
e390: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
e3a0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
e3b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
e3c0: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
e3d0: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
e3e0: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
e3f0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
e400: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
e410: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
e420: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
e430: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
e440: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
e450: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
e460: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
e470: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
e480: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
e490: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
e4a0: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
e4b0: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
e4c0: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
e4d0: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
e4e0: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
e4f0: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
e500: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
e510: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
e520: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
e530: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
e540: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
e550: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
e560: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
e570: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
e580: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
e590: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
e5a0: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
e5b0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e5c0: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
e5d0: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
e5e0: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
e5f0: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
e600: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
e610: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
e620: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
e630: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
e640: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
e650: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
e660: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
e670: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e680: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
e690: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
e6a0: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
e6b0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
e6c0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
e6d0: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
e6e0: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
e6f0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
e700: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
e710: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
e720: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
e730: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
e740: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
e750: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
e760: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
e770: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
e780: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
e790: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
e7a0: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
e7b0: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
e7c0: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
e7d0: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
e7e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
e7f0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
e800: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
e810: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
e820: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
e830: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
e840: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
e850: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
e860: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
e870: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
e880: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
e890: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
e8a0: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
e8b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
e8c0: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
e8d0: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
e8e0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
e8f0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
e900: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
e910: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
e920: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
e930: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
e940: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
e950: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
e960: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
e970: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
e980: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
e990: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
e9a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
e9b0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
e9c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
e9d0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
e9e0: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
e9f0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
ea00: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
ea10: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
ea20: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
ea30: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
ea40: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
ea50: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
ea60: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
ea70: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
ea80: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
ea90: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
eaa0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
eab0: 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
eac0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
ead0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
eae0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
eaf0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
eb00: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
eb10: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
eb20: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
eb30: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
eb40: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
eb50: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
eb60: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
eb70: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
eb80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
eb90: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
eba0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ebb0: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
ebc0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
ebd0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
ebe0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
ebf0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
ec00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ec10: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
ec20: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
ec30: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
ec40: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ec50: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
ec60: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
ec70: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
ec80: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
ec90: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
eca0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
ecb0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
ecc0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
ecd0: 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
ece0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
ecf0: 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
ed00: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
ed10: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
ed20: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
ed30: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
ed40: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
ed50: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
ed60: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
ed70: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
ed80: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
ed90: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
eda0: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
edb0: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
edc0: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
edd0: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
ede0: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
edf0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
ee00: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
ee10: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
ee20: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
ee30: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
ee40: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
ee50: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ee60: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
ee70: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
ee80: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
ee90: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
eea0: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
eeb0: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
eec0: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
eed0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
eee0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
eef0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
ef00: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
ef10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ef20: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
ef30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ef40: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
ef50: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
ef60: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
ef70: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ef80: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
ef90: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
efa0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
efb0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
efc0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
efd0: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
efe0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
eff0: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
f000: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
f010: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
f020: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
f030: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
f040: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
f050: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
f060: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f070: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
f080: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
f090: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
f0a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f0b0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
f0c0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
f0d0: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
f0e0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
f0f0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
f100: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
f110: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
f120: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
f130: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
f140: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
f150: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
f160: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
f170: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f180: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
f190: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
f1a0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f1b0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f1c0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f1d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f1e0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f1f0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f200: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
f210: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
f220: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
f230: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
f240: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f250: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
f260: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
f270: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
f280: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
f290: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f2a0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f2b0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
f2c0: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
f2d0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
f2e0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f2f0: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
f300: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
f310: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
f320: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
f330: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
f340: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
f350: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
f360: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
f370: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
f380: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
f390: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
f3a0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
f3b0: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
f3c0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
f3d0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
f3e0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
f3f0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
f400: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
f410: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
f420: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
f430: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
f440: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
f450: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
f460: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
f470: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
f480: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
f490: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f4a0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
f4b0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
f4c0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
f4d0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
f4e0: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
f4f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f500: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
f510: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
f520: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
f530: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
f540: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
f550: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
f560: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f570: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
f580: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
f590: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
f5a0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
f5b0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
f5c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
f5d0: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
f5e0: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
f5f0: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
f600: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f610: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
f620: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
f630: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
f640: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
f650: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
f660: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f670: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
f680: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f690: 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
f6a0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
f6b0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f6c0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f6d0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
f6e0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
f6f0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
f700: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
f710: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f720: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
f730: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
f740: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
f750: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
f760: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f770: 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
f780: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
f790: 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
f7a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f7b0: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
f7c0: 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
f7d0: 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
f7e0: 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
f7f0: 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
f800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
f810: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
f820: 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
f830: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
f840: 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
f850: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
f860: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
f870: 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
f880: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f890: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
f8a0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f8b0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f8c0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f8d0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f8e0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f8f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f900: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
f910: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
f920: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
f930: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
f940: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
f950: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
f960: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
f970: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
f980: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
f990: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
f9a0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
f9b0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
f9c0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
f9d0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
f9e0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
f9f0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
fa00: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
fa10: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
fa20: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
fa30: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
fa40: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fa50: 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
fa60: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
fa70: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
fa80: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
fa90: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
faa0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
fab0: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
fac0: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
fad0: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
fae0: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
faf0: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
fb00: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fb10: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
fb20: 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
fb30: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
fb40: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
fb50: 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
fb60: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
fb70: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
fb80: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
fb90: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
fba0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
fbb0: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
fbc0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
fbd0: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
fbe0: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
fbf0: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
fc00: 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
fc10: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
fc20: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
fc30: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
fc40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
fc50: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
fc60: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
fc70: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
fc80: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
fc90: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
fca0: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
fcb0: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
fcc0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
fcd0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
fce0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
fcf0: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
fd00: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
fd10: 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
fd20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
fd30: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
fd40: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
fd50: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
fd60: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
fd70: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
fd80: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
fd90: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
fda0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
fdb0: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
fdc0: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
fdd0: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
fde0: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
fdf0: 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
fe00: 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
fe10: 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
fe20: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
fe30: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
fe40: 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
fe50: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
fe60: 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
fe70: 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
fe80: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
fe90: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
fea0: 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20  e of 16..** The 
feb0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
fec0: 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
fed0: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
fee0: 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
fef0: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
ff00: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
ff10: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
ff20: 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
ff30: 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62  an two scratch b
ff40: 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
ff50: 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
ff60: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69  ld be set to twi
ff70: 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20  ce the expected 
ff80: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
ff90: 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53  f threads..** ^S
ffa0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
ffb0: 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
ffc0: 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
ffd0: 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
ffe0: 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
fff0: 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  ase page size. ^
10000 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
10010 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
10020 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
10030 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
10040 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
10050 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
10060 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
10070 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
10080 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
10090 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
100a0 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
100b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
100c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
100d0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
100e0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
100f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
10100 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
10110 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
10120 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
10130 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
10140 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
10150 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
10160 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
10170 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
10180 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
10190 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
101a0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
101b0 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
101c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
101d0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
101e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
101f0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
10200 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
10210 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a  CACHE2 option..*
10220 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10230 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
10240 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
10250 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
10260 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
10270 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
10280 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
10290 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
102a0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
102b0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
102c0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
102d0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
102e0 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
102f0 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
10300 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
10310 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
10320 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
10330 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
10340 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
10350 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
10360 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
10370 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
10380 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
10390 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
103a0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
103b0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
103c0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
103d0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
103e0 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
103f0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
10400 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
10410 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
10420 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
10430 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
10440 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
10450 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
10460 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
10470 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10480 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
10490 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
104a0 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
104b0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
104c0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
104d0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
104e0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
104f0 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
10500 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
10510 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
10520 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
10530 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
10540 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10550 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
10560 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
10570 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
10580 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
10590 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
105a0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
105b0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
105c0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
105d0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
105e0 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
105f0 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
10600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10610 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
10620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
10630 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
10640 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
10650 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
10660 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
10670 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
10680 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
10690 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
106a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
106b0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
106c0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
106d0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
106e0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
106f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10700 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
10710 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
10720 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
10730 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
10740 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
10750 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
10760 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
10770 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
10780 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
10790 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
107a0 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
107b0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
107c0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
107d0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
107e0 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
107f0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
10800 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
10810 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
10820 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
10830 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
10840 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
10850 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
10860 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10870 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
10880 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
10890 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
108a0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
108b0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
108c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
108d0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
108e0 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
108f0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
10900 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10910 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
10920 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
10930 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
10940 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
10950 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
10960 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
10970 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
10980 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
10990 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
109a0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
109b0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
109c0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
109d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
109e0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
109f0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
10a00 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
10a10 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
10a20 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
10a30 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
10a40 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
10a50 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
10a60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10a70 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
10a80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
10a90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10aa0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10ab0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10ac0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10ad0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10ae0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
10af0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
10b00 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10b10 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
10b20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
10b30 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
10b40 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
10b50 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
10b60 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
10b70 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
10b80 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
10b90 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
10ba0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
10bb0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
10bc0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10bd0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10be0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
10bf0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
10c00 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
10c10 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
10c20 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10c30 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10c40 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10c50 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10c60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10c70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
10c80 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
10c90 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
10ca0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
10cb0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
10cc0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
10cd0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
10ce0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
10cf0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
10d00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10d10 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
10d20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
10d30 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10d40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
10d50 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
10d60 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
10d70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10d80 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10d90 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10da0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10db0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10dc0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
10dd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
10de0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10df0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
10e00 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10e10 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
10e20 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
10e30 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
10e40 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
10e50 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
10e60 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
10e70 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
10e80 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
10e90 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
10ea0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
10eb0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
10ec0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
10ed0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
10ee0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
10ef0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
10f00 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
10f10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10f20 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
10f30 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
10f40 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10f50 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
10f60 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
10f70 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
10f80 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
10f90 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
10fa0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
10fb0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
10fc0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10fd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10fe0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
10ff0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11000 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
11010 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11020 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
11030 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11040 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
11050 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11060 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
11070 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
11080 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
11090 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
110a0 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
110b0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
110c0 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
110d0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
110e0 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
110f0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
11100 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
11110 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11120 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
11130 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
11140 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
11150 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
11160 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11170 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
11180 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
11190 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
111a0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
111b0 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
111c0 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
111d0 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
111e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
111f0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
11200 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11210 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
11220 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
11230 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
11240 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11250 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
11260 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
11270 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11280 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
11290 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
112a0 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
112b0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
112c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
112d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
112e0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
112f0 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
11300 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
11310 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
11320 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
11330 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
11340 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
11350 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
11360 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
11370 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
11380 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
11390 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
113a0 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
113b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
113c0 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
113d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
113e0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
113f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11400 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
11410 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11420 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11430 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11440 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11450 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
11460 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
11470 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
11480 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20  e copies of the 
11490 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20  current.** page 
114a0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
114b0 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
114c0 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
114d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
114e0 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
114f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
11500 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11510 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11520 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
11530 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
11540 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
11550 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
11560 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
11570 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
11580 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
11590 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
115a0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
115b0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
115c0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
115d0 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
115e0 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
115f0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
11600 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
11610 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
11620 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
11630 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
11640 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
11650 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
11660 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
11670 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
11680 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
11690 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
116a0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
116b0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
116c0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
116d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
116e0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
116f0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
11700 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
11710 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
11720 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
11730 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
11740 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
11750 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
11760 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
11770 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
11780 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
11790 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
117a0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
117b0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
117c0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
117d0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
117e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
117f0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
11800 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
11810 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
11820 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
11830 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
11840 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
11850 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
11860 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
11870 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
11880 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
11890 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
118a0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
118b0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
118c0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
118d0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
118e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
118f0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
11900 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
11910 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
11920 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
11930 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
11940 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
11950 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11960 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
11970 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11980 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
11990 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
119a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
119b0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
119c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
119d0 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
119e0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
119f0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
11a00 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
11a10 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
11a20 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
11a30 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
11a40 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
11a50 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
11a60 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
11a70 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
11a80 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
11a90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
11aa0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
11ab0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
11ac0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
11ad0 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
11ae0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
11af0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
11b00 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
11b10 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
11b20 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
11b30 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
11b40 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
11b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
11b60 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
11b70 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
11b80 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
11b90 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
11ba0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
11bb0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
11bc0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
11bd0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
11be0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11bf0 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
11c00 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
11c10 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
11c20 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
11c30 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
11c40 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
11c50 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
11c60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
11c70 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
11c80 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
11c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
11ca0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
11cb0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
11cc0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
11cd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
11ce0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 4e 49  nd SQLITE_CONFNI
11cf0 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
11d00 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
11d10 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
11d20 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
11d30 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
11d40 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
11d50 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
11d60 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
11d70 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
11d80 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e  no-ops..** </dl>
11d90 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11da0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11db0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
11dc0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
11dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11de0 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
11df0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
11e00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11e10 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
11e20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
11e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11e40 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
11e50 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11e60 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
11e70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
11e80 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
11e90 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
11ea0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
11eb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11ec0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
11ed0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
11ee0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
11ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11f00 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
11f10 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
11f20 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
11f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11f40 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
11f50 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
11f60 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
11f70 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
11f80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11f90 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
11fa0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
11fb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11fc0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
11fd0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
11fe0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
11ff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12000 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
12010 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
12020 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
12030 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
12040 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
12050 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
12060 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
12070 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
12080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
12090 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
120a0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
120b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
120c0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
120d0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
120e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
120f0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
12100 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
12110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12120 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
12130 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
12140 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
12150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12160 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
12170 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
12180 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12190 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
121a0 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
121b0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
121c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
121d0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
121e0 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
121f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
12200 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ds2* */../*.** C
12210 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
12220 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
12230 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
12240 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
12250 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12260 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12270 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12290 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
122a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
122b0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
122c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
122d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
122e0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
122f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
12300 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
12310 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
12320 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
12330 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
12340 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
12350 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
12360 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
12370 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
12380 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
12390 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
123a0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
123b0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
123c0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
123d0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
123e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
123f0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
12400 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
12410 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
12420 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
12430 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
12440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12450 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
12460 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
12470 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
12480 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
12490 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
124a0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
124b0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
124c0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
124d0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
124e0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
124f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
12500 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
12510 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
12520 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
12530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12540 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
12550 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
12560 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
12570 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
12580 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
12590 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
125a0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
125b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
125c0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
125d0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
125e0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
125f0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
12600 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
12610 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
12620 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
12630 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
12640 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
12650 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
12660 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12670 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
12680 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
12690 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
126a0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
126b0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
126c0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
126d0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
126e0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
126f0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
12700 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
12710 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
12720 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
12730 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
12740 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
12750 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
12760 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
12770 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
12780 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
12790 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
127a0 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
127b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
127c0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
127d0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
127e0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
127f0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
12800 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
12810 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
12820 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
12830 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
12840 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
12850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
12860 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
12870 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
12880 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
12890 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
128a0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
128b0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
128c0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
128d0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
128e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
128f0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
12900 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
12910 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
12920 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
12930 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
12940 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
12950 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
12960 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
12970 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
12980 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
12990 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
129a0 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
129b0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
129c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
129d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
129e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
129f0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
12a00 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12a10 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
12a20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
12a30 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
12a40 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
12a50 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
12a60 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
12a70 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
12a80 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
12a90 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12aa0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
12ab0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
12ac0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
12ad0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
12ae0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
12af0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
12b00 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
12b10 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
12b20 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
12b30 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
12b40 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
12b50 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
12b60 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
12b70 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
12b80 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
12b90 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
12ba0 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
12bb0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
12bc0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
12bd0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
12be0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
12bf0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
12c00 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
12c10 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
12c20 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
12c30 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
12c40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
12c50 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
12c60 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
12c70 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12c80 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
12c90 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
12ca0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
12cb0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
12cc0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
12cd0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
12ce0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
12cf0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
12d00 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
12d10 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
12d20 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
12d30 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
12d40 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
12d50 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
12d60 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
12d70 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
12d80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
12d90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12da0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
12db0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
12dc0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
12dd0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
12de0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
12df0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
12e00 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
12e10 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
12e20 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
12e30 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
12e40 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
12e50 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
12e60 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
12e70 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
12e80 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
12e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12ea0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12eb0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
12ec0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
12ed0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
12ee0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
12ef0 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
12f00 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
12f10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12f20 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
12f30 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
12f40 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
12f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12f60 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
12f70 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
12f80 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
12f90 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
12fa0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
12fb0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
12fc0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
12fd0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
12fe0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
12ff0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
13000 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
13010 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
13020 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
13030 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
13040 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
13050 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
13060 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
13070 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
13080 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
13090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
130a0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
130b0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
130c0 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
130d0 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
130e0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
130f0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
13100 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
13110 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
13120 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
13130 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
13140 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
13150 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
13160 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
13170 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
13180 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
13190 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
131a0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
131b0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
131c0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
131d0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
131e0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
131f0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
13200 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
13210 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
13220 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
13230 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
13240 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
13250 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
13260 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
13270 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
13280 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
13290 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
132a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
132b0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
132c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
132d0 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20    ^As of SQLite 
132e0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74  version 3.7.7, t
132f0 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  his routines.** 
13300 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74  records the last
13310 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66   insert rowid of
13320 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74   both ordinary t
13330 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75  ables and [virtu
13340 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e  al tables]..** ^
13350 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
13360 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
13370 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
13380 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
13390 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
133a0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
133b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
133c0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
133d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
133e0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
133f0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
13400 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
13410 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
13420 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
13430 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
13440 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
13450 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
13460 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
13470 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
13480 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
13490 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
134a0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
134b0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
134c0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
134d0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
134e0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
134f0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
13500 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
13510 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
13520 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
13530 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
13540 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
13550 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
13560 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
13570 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
13580 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
13590 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
135a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
135b0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
135c0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
135d0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
135e0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
135f0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
13600 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
13610 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
13620 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
13630 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
13640 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
13650 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
13660 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
13670 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
13680 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
13690 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
136a0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
136b0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
136c0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
136d0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
136e0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
136f0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
13700 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
13710 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
13720 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
13730 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
13740 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
13750 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
13760 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
13770 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
13780 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
13790 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
137a0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
137b0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
137c0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
137d0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
137e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
137f0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
13800 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
13810 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
13820 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
13830 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
13840 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
13850 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
13860 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
13870 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
13880 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
13890 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
138a0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
138b0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
138c0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
138d0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
138e0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
138f0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
13900 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
13910 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
13920 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
13930 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
13940 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
13950 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
13960 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
13970 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
13980 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
13990 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
139a0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
139b0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
139c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
139d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
139e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
139f0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
13a00 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
13a10 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
13a20 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
13a30 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
13a40 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
13a50 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
13a60 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
13a70 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
13a80 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
13a90 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
13aa0 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
13ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13ac0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
13ad0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13ae0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
13af0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
13b00 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
13b10 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
13b20 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
13b30 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
13b40 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
13b50 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
13b60 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
13b70 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
13b80 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
13b90 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
13ba0 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
13bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
13bc0 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
13bd0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
13be0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
13bf0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
13c00 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
13c10 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
13c20 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
13c30 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
13c40 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
13c50 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
13c60 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
13c70 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
13c80 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
13c90 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
13ca0 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
13cb0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
13cc0 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
13cd0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
13ce0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
13cf0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
13d00 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
13d10 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
13d20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
13d30 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
13d40 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
13d50 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
13d60 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
13d70 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
13d80 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
13d90 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
13da0 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
13db0 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
13dc0 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
13dd0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
13de0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
13df0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
13e00 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
13e10 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
13e20 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
13e30 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
13e40 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
13e50 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
13e60 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
13e70 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
13e80 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
13e90 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
13ea0 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
13eb0 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
13ec0 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
13ed0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
13ee0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
13ef0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
13f00 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
13f10 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
13f20 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
13f30 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
13f40 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
13f50 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
13f60 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
13f70 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
13f80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
13f90 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
13fa0 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
13fb0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
13fc0 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
13fd0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
13fe0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
13ff0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14000 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14010 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
14020 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
14030 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
14040 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
14050 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
14060 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
14070 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
14080 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
14090 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
140a0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
140b0 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
140c0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
140d0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
140e0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
140f0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
14100 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
14110 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
14120 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
14130 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
14140 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
14150 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
14160 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
14170 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
14180 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
14190 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
141a0 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
141b0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
141c0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
141d0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
141e0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
141f0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
14200 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
14210 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
14220 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
14230 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
14240 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
14250 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
14260 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
14270 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
14280 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
14290 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
142a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
142b0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
142c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
142d0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
142e0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
142f0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
14300 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
14310 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
14320 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
14330 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
14340 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14350 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
14360 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
14370 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
14380 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
14390 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
143a0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
143b0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
143c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
143d0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
143e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
143f0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
14400 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
14410 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
14420 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
14430 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
14440 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
14450 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
14460 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
14470 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
14480 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
14490 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
144a0 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
144b0 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
144c0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
144d0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
144e0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
144f0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
14500 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
14510 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
14520 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
14530 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
14540 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
14550 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
14560 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
14570 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
14580 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
14590 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
145a0 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
145b0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
145c0 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
145d0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
145e0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
145f0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
14600 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
14610 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
14620 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
14630 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
14640 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
14650 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
14660 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
14670 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
14680 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
14690 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
146a0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
146b0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
146c0 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
146d0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
146e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
146f0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
14700 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
14710 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
14720 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
14730 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
14740 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
14750 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
14760 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
14770 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
14780 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
14790 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
147a0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
147b0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
147c0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
147d0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
147e0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
147f0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
14800 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
14810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14820 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
14830 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
14840 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
14850 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
14860 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
14870 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
14880 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
14890 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
148a0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
148b0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
148c0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
148d0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
148e0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
148f0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
14900 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
14910 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
14920 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
14930 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
14940 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
14950 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
14960 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
14970 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
14980 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
14990 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
149a0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
149b0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
149c0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
149d0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
149e0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
149f0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
14a00 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
14a10 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
14a20 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
14a30 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
14a40 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
14a50 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
14a60 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
14a70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
14a80 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
14a90 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
14aa0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
14ab0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
14ac0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14ad0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
14ae0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
14af0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
14b00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
14b10 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
14b20 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
14b30 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
14b40 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
14b50 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
14b60 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14b70 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
14b80 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
14b90 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
14ba0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
14bb0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
14bc0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
14bd0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
14be0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
14bf0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
14c00 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
14c10 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
14c20 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
14c30 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
14c40 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
14c50 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
14c60 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
14c70 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
14c80 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
14c90 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
14ca0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
14cb0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
14cc0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
14cd0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
14ce0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
14cf0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
14d00 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
14d10 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
14d20 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
14d30 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
14d40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14d50 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
14d60 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
14d70 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
14d80 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
14d90 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
14da0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
14db0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
14dc0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
14dd0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
14de0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
14df0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
14e00 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
14e10 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
14e20 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
14e30 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
14e40 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
14e50 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
14e60 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
14e70 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
14e80 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
14e90 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
14ea0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
14eb0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
14ec0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
14ed0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
14ee0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
14ef0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
14f00 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
14f10 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
14f20 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
14f30 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
14f40 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
14f50 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
14f60 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
14f70 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
14f80 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
14f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14fa0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
14fb0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
14fc0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
14fd0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
14fe0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
14ff0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
15000 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
15010 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
15020 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15030 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
15040 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
15050 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
15060 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15070 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
15080 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
15090 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
150a0 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
150b0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
150c0 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
150d0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
150e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
150f0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
15100 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
15110 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
15120 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
15130 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
15140 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
15150 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
15160 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
15170 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
15180 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
15190 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
151a0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
151b0 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
151c0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
151d0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
151e0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
151f0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
15200 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
15210 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
15220 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
15230 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
15240 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
15250 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
15260 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
15270 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
15280 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
15290 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
152a0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
152b0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
152c0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
152d0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
152e0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
152f0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
15300 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
15310 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
15320 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
15330 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
15340 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
15350 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
15360 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
15370 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
15380 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
15390 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
153a0 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
153b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
153c0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
153d0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
153e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
153f0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
15400 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
15410 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
15420 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
15430 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
15440 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
15450 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
15460 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
15470 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
15480 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
15490 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
154a0 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
154b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
154c0 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
154d0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
154e0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
154f0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
15500 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
15510 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
15520 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
15530 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
15540 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
15550 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
15560 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
15570 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
15580 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
15590 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
155a0 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
155b0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
155c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
155d0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
155e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
155f0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
15600 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
15610 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
15620 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
15630 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
15640 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
15650 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
15660 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
15670 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
15680 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
15690 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
156a0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
156b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
156c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
156d0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
156e0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
156f0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
15700 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
15710 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
15720 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
15730 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
15740 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
15750 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
15760 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
15770 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
15780 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
15790 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
157a0 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
157b0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
157c0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
157d0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
157e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
157f0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
15800 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
15810 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
15820 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
15830 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
15840 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
15850 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
15860 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
15870 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
15880 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
15890 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
158a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
158b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
158c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
158d0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
158e0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
158f0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
15900 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
15910 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
15920 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15930 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
15940 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
15950 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
15960 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
15970 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
15980 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
15990 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
159a0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
159b0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
159c0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
159d0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
159e0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
159f0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
15a00 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
15a10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
15a20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
15a30 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
15a40 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
15a50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15a60 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
15a70 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
15a80 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
15a90 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
15aa0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
15ab0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
15ac0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
15ad0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
15ae0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
15af0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
15b00 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
15b10 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
15b20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
15b30 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
15b40 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
15b50 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
15b60 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
15b70 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
15b80 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
15b90 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
15ba0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
15bb0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
15bc0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
15bd0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
15be0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
15bf0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
15c00 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
15c10 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
15c20 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
15c30 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
15c40 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
15c50 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
15c60 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
15c70 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
15c80 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
15c90 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
15ca0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
15cb0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
15cc0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
15cd0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
15ce0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
15cf0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
15d00 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
15d10 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
15d20 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
15d30 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
15d40 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
15d50 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
15d60 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
15d70 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
15d80 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
15d90 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
15da0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
15db0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
15dc0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
15dd0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
15de0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
15df0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
15e00 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
15e10 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
15e20 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
15e30 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
15e40 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
15e50 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
15e60 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
15e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
15e80 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
15e90 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
15ea0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
15eb0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
15ec0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
15ed0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
15ee0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
15ef0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
15f00 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
15f10 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
15f20 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
15f30 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
15f40 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
15f50 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
15f60 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
15f70 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
15f80 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
15f90 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
15fa0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
15fb0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
15fc0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
15fd0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
15fe0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
15ff0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
16000 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
16010 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
16020 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
16030 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
16040 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
16050 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
16060 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
16070 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
16080 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
16090 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
160a0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
160b0 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
160c0 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
160d0 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
160e0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
160f0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
16100 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16110 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
16120 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
16130 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
16140 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
16150 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
16160 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
16170 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
16180 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
16190 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
161a0 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
161b0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
161c0 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
161d0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
161e0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
161f0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
16200 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
16210 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
16220 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
16230 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
16240 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
16250 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
16260 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
16270 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
16280 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
16290 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
162a0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
162b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
162c0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
162d0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
162e0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
162f0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
16300 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
16310 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
16320 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
16330 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
16340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16350 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
16360 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
16370 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
16380 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
16390 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
163a0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
163b0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
163c0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
163d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
163e0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
163f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
16400 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
16410 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
16420 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
16430 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
16440 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
16450 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
16460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
16470 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
16480 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
16490 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
164a0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
164b0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
164c0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
164d0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
164e0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
164f0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
16500 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
16510 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
16520 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
16530 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
16540 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
16550 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
16560 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
16570 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
16580 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
16590 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
165a0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
165b0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
165c0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
165d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
165e0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
165f0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
16600 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16610 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
16620 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
16630 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
16640 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
16650 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
16660 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
16670 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
16680 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
16690 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
166a0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
166b0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
166c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
166d0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
166e0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
166f0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
16700 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
16710 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
16720 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
16730 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
16740 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
16750 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
16760 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
16770 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
16780 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
16790 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
167a0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
167b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
167c0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
167d0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
167e0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
167f0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
16800 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
16810 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
16820 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
16830 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
16840 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
16850 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
16860 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
16870 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
16880 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
16890 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
168a0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
168b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
168c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
168d0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
168e0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
168f0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
16900 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
16910 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
16920 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
16930 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
16940 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
16950 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
16960 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
16970 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
16980 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
16990 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
169a0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
169b0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
169c0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
169d0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
169e0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
169f0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
16a00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
16a10 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
16a20 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
16a30 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
16a40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
16a50 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
16a60 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
16a70 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
16a80 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
16a90 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
16aa0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
16ab0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
16ac0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
16ad0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
16ae0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
16af0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
16b00 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
16b10 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
16b20 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
16b30 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
16b40 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
16b50 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
16b60 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
16b70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
16b80 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
16b90 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
16ba0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
16bb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
16bc0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
16bd0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
16be0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
16bf0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
16c00 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
16c10 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
16c20 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
16c30 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
16c40 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
16c50 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
16c60 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
16c70 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
16c80 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
16c90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
16ca0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
16cb0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
16cc0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
16cd0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
16ce0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
16cf0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16d00 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
16d10 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
16d20 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
16d30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16d40 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
16d50 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
16d60 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
16d70 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
16d80 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
16d90 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
16da0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16db0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
16dc0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
16dd0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
16de0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
16df0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
16e00 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
16e10 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
16e20 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
16e30 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
16e40 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
16e50 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
16e60 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
16e70 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
16e80 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16e90 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16ea0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
16eb0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
16ec0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
16ed0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
16ee0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
16ef0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
16f00 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
16f10 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
16f20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16f30 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
16f40 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
16f50 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
16f60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16f70 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
16f80 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
16f90 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
16fa0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
16fb0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
16fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16fd0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
16fe0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
16ff0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
17000 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
17010 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
17020 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
17030 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
17040 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
17050 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
17060 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
17070 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
17080 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
17090 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
170a0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
170b0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
170c0 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
170d0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
170e0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
170f0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
17100 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
17110 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
17120 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
17130 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
17140 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
17150 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
17160 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
17170 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
17180 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
17190 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
171a0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
171b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
171c0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
171d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
171e0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
171f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17200 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
17210 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
17220 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
17230 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
17240 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
17250 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
17260 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
17270 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
17280 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
17290 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
172a0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
172b0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
172c0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
172d0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
172e0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
172f0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
17300 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
17310 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
17320 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
17330 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
17340 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
17350 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
17360 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
17370 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
17380 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
17390 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
173a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
173b0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
173c0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
173d0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
173e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
173f0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
17400 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
17410 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
17420 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
17430 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
17440 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
17450 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
17460 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
17470 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
17480 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
17490 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
174a0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
174b0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
174c0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
174d0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
174e0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
174f0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
17500 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
17510 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
17520 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
17530 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
17540 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
17550 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
17560 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
17570 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
17580 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
17590 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
175a0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
175b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
175c0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
175d0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
175e0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
175f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
17600 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
17610 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
17620 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
17630 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
17640 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
17650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17660 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
17670 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
17680 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
17690 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
176a0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
176b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
176c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
176d0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
176e0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
176f0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
17700 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
17710 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
17720 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
17730 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
17740 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
17750 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
17760 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
17770 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
17780 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
17790 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
177a0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
177b0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
177c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
177d0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
177e0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
177f0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
17800 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
17810 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
17820 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
17830 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
17840 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17850 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
17860 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
17870 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
17880 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
17890 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
178a0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
178b0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
178c0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
178d0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
178e0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
178f0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
17900 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
17910 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
17920 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
17930 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
17940 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
17950 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
17960 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
17970 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
17980 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
17990 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
179a0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
179b0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
179c0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
179d0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
179e0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
179f0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
17a00 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
17a10 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
17a20 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
17a30 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
17a40 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
17a50 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
17a60 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
17a70 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
17a80 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
17a90 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
17aa0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
17ab0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
17ac0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
17ad0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
17ae0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
17af0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
17b00 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
17b10 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
17b20 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
17b30 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
17b40 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
17b50 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
17b60 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
17b70 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
17b80 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
17b90 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
17ba0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
17bb0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
17bc0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
17bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
17be0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
17bf0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
17c00 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
17c10 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
17c20 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
17c30 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
17c40 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
17c50 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
17c60 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
17c70 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
17c80 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
17c90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
17ca0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
17cb0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
17cc0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
17cd0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
17ce0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
17cf0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
17d00 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
17d10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
17d20 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
17d30 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
17d40 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
17d50 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
17d60 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
17d70 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
17d80 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
17d90 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
17da0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
17db0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
17dc0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
17dd0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
17de0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
17df0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
17e00 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
17e10 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
17e20 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
17e30 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
17e40 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
17e50 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
17e60 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
17e70 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
17e80 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
17e90 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
17ea0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
17eb0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
17ec0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
17ed0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
17ee0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
17ef0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
17f00 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
17f10 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
17f20 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
17f30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17f40 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
17f50 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
17f60 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
17f70 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
17f80 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
17f90 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
17fa0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
17fb0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
17fc0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
17fd0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17fe0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
17ff0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
18000 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
18010 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
18020 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
18030 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
18040 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
18050 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
18060 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18070 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
18080 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
18090 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
180a0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
180b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
180c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
180d0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
180e0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
180f0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
18100 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
18110 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
18120 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
18130 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18140 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
18150 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
18160 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
18170 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
18180 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
18190 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
181a0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
181b0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
181c0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
181d0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
181e0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
181f0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
18200 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
18210 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
18220 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
18230 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
18240 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
18250 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
18260 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
18270 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
18280 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
18290 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
182a0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
182b0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
182c0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
182d0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
182e0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
182f0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
18300 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
18310 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
18320 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
18330 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
18340 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
18350 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18360 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
18370 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
18380 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
18390 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
183a0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
183b0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
183c0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
183d0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
183e0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
183f0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
18400 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
18410 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
18420 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
18430 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
18440 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
18450 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
18460 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
18470 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
18480 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
18490 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
184a0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
184b0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
184c0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
184d0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
184e0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
184f0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
18500 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
18510 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
18520 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
18530 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
18540 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
18550 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
18560 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
18570 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
18580 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
18590 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
185a0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
185b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
185c0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
185d0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
185e0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
185f0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
18600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18610 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
18620 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
18630 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
18640 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
18650 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
18660 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
18670 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
18680 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
18690 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
186a0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
186b0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
186c0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
186d0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
186e0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
186f0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
18700 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
18710 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
18720 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
18730 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
18740 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18750 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
18760 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
18770 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
18780 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
18790 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
187a0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
187b0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
187c0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
187d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
187e0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
187f0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
18800 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
18810 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
18820 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
18830 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
18840 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18850 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
18860 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
18870 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
18880 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
18890 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
188a0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
188b0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
188c0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
188d0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
188e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
188f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
18900 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
18910 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
18920 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
18930 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
18940 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
18950 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
18960 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
18970 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
18980 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
18990 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
189a0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
189b0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
189c0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
189d0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
189e0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
189f0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
18a00 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
18a10 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
18a20 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
18a30 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
18a40 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
18a50 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
18a60 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
18a70 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
18a80 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
18a90 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
18aa0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
18ab0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
18ac0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
18ad0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
18ae0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
18af0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
18b00 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
18b10 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
18b20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
18b30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
18b40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
18b50 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
18b60 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
18b70 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
18b80 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
18b90 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
18ba0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
18bb0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
18bc0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
18bd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
18be0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
18bf0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
18c00 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
18c10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
18c20 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
18c30 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
18c40 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
18c50 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
18c60 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
18c70 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
18c80 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
18c90 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
18ca0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18cb0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
18cc0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
18cd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
18ce0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
18cf0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
18d00 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
18d10 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
18d20 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
18d30 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
18d40 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
18d50 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
18d60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
18d70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
18d80 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
18d90 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
18da0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
18db0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
18dc0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
18dd0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
18de0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
18df0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
18e00 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
18e10 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
18e20 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
18e30 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
18e40 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
18e50 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
18e60 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
18e70 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
18e80 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
18e90 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
18ea0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
18eb0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
18ec0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
18ed0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
18ee0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
18ef0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
18f00 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
18f10 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
18f20 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
18f30 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
18f40 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
18f50 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
18f60 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
18f70 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
18f80 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
18f90 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
18fa0 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
18fb0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
18fc0 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
18fd0 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
18fe0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
18ff0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
19000 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
19010 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
19020 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
19030 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
19040 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
19050 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
19060 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
19070 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
19080 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
19090 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
190a0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
190b0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
190c0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
190d0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
190e0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
190f0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
19100 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
19110 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
19120 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
19130 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
19140 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
19150 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
19160 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
19170 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
19180 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
19190 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
191a0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
191b0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
191c0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
191d0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
191e0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
191f0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
19200 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
19210 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
19220 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
19230 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
19240 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
19250 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
19260 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
19270 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
19280 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
19290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
192a0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
192b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
192c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
192d0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
192e0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
192f0 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
19300 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
19310 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
19320 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
19330 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
19340 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19350 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
19360 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
19370 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
19380 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
19390 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
193a0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
193b0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
193c0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
193d0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
193e0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
193f0 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
19400 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
19410 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
19420 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
19430 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
19440 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
19450 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
19460 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
19470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
19480 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
19490 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
194a0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
194b0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
194c0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
194d0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
194e0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
194f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
19500 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
19510 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
19520 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
19530 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
19540 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
19550 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
19560 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
19570 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
19580 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
19590 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
195a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
195b0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
195c0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
195d0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
195e0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
195f0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
19600 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
19610 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
19620 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
19630 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
19640 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
19650 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
19660 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
19670 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
19680 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
19690 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
196a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
196b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
196c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
196d0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
196e0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
196f0 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
19700 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
19710 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
19720 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
19730 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
19740 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
19750 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
19760 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
19770 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
19780 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
19790 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
197a0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
197b0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
197c0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
197d0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
197e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
197f0 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
19800 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
19810 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
19820 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
19830 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
19840 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
19850 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
19860 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
19870 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
19880 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
19890 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
198a0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
198b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
198c0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
198d0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
198e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
198f0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
19900 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
19910 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
19920 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
19930 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
19940 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
19950 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
19960 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
19970 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
19980 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
19990 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
199a0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
199b0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
199c0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
199d0 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
199e0 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
199f0 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
19a00 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
19a10 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
19a20 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
19a30 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
19a40 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
19a50 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
19a60 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
19a70 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
19a80 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
19a90 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
19aa0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
19ab0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
19ac0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
19ad0 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
19ae0 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
19af0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
19b00 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
19b10 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
19b20 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
19b30 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
19b40 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
19b50 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
19b60 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
19b70 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
19b80 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
19b90 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
19ba0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
19bb0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
19bc0 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
19bd0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
19be0 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
19bf0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
19c00 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
19c10 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
19c20 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
19c30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
19c40 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
19c50 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
19c60 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
19c70 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
19c80 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
19c90 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
19ca0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
19cb0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
19cc0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
19cd0 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
19ce0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19cf0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
19d00 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19d10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
19d20 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
19d30 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
19d40 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
19d50 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
19d60 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
19d70 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
19d80 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
19d90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
19da0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
19db0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
19dc0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
19dd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
19de0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19df0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
19e00 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
19e10 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
19e20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
19e30 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
19e40 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
19e50 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
19e60 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
19e70 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
19e80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19e90 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
19ea0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
19eb0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
19ec0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19ed0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
19ee0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
19ef0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
19f00 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
19f10 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
19f20 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
19f30 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
19f40 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
19f50 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
19f60 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
19f70 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
19f80 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
19f90 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
19fa0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
19fb0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
19fc0 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
19fd0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19fe0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
19ff0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1a000 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1a010 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1a020 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1a030 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1a040 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1a050 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1a060 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1a070 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1a080 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1a090 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1a0a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1a0b0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1a0c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1a0d0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1a0e0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1a0f0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1a100 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1a110 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1a120 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1a130 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1a140 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a150 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1a160 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1a170 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1a180 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1a190 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1a1a0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1a1b0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1a1c0 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1a1d0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1a1e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1a1f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a200 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1a210 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1a220 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1a230 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a240 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1a250 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1a260 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1a270 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a280 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1a290 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1a2a0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1a2b0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1a2c0 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1a2d0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1a2e0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1a2f0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1a300 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1a310 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1a320 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1a330 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1a340 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1a350 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1a360 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1a370 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1a380 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1a390 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1a3a0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1a3b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1a3c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1a3d0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1a3e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1a3f0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1a400 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1a410 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1a420 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1a430 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1a440 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1a450 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1a460 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1a470 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1a480 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1a490 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1a4a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a4b0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1a4c0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1a4d0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1a4e0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1a4f0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1a500 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1a510 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1a520 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1a530 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1a540 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1a550 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1a560 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1a570 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1a580 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1a590 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1a5a0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1a5b0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1a5c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1a5d0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1a5e0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1a5f0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1a600 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1a610 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1a620 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1a630 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1a640 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1a650 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1a660 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1a670 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1a680 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1a690 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1a6a0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1a6b0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1a6c0 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1a6d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1a6e0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1a6f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1a700 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1a710 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1a720 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1a730 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1a740 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1a750 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1a760 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1a770 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1a780 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1a790 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1a7a0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1a7b0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1a7c0 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1a7d0 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1a7e0 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1a7f0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1a800 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1a810 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1a820 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1a830 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1a840 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1a850 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1a860 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1a870 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1a880 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1a890 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1a8a0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1a8b0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1a8c0 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1a8d0 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1a8e0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1a8f0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1a900 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1a910 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1a920 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1a930 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1a940 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1a950 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1a960 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1a970 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1a980 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1a990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a9a0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1a9b0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1a9c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a9d0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1a9e0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1a9f0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1aa00 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1aa10 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1aa20 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1aa30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1aa40 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1aa50 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1aa60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1aa70 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1aa80 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1aa90 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1aaa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aab0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1aac0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1aad0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1aae0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1aaf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1ab00 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1ab10 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1ab20 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1ab30 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1ab40 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1ab50 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1ab60 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1ab70 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1ab80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1ab90 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1aba0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1abb0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1abc0 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1abd0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1abe0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1abf0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1ac00 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1ac10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ac20 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1ac30 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1ac40 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1ac50 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1ac60 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1ac70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1ac80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1ac90 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1aca0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1acb0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1acc0 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1acd0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1ace0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1acf0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1ad00 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1ad10 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1ad20 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1ad30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1ad40 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1ad50 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1ad60 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1ad70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1ad80 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1ad90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1ada0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1adb0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1adc0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1add0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
1ade0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1adf0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1ae00 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1ae10 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1ae20 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1ae30 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1ae40 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1ae50 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1ae60 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1ae70 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1ae80 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1ae90 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1aea0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1aeb0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1aec0 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1aed0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1aee0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1aef0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1af00 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1af10 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1af20 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1af30 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1af40 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1af50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1af60 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1af70 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1af80 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1af90 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1afa0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1afb0 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1afc0 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1afd0 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1afe0 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1aff0 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1b000 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1b010 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1b020 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1b030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b040 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1b050 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1b060 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1b070 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1b080 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1b090 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1b0a0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1b0b0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1b0c0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1b0d0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1b0e0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1b0f0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1b100 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b110 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1b120 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1b130 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1b140 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1b150 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1b160 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1b170 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1b180 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1b190 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1b1a0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1b1b0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1b1c0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1b1d0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1b1e0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1b1f0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1b200 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1b210 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1b220 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1b230 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1b240 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1b250 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1b260 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1b270 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1b280 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1b290 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1b2a0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1b2b0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1b2c0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1b2d0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1b2e0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1b2f0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1b300 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1b310 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1b320 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1b330 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1b340 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1b350 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1b360 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1b370 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1b380 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1b390 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1b3a0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1b3b0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1b3c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1b3d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b3e0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1b3f0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1b400 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1b410 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1b420 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1b430 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1b440 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1b450 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1b460 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1b470 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1b480 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1b490 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b4a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b4b0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1b4c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1b4d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1b4e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b4f0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1b500 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1b510 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1b520 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b530 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b540 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1b550 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b560 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b580 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b590 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1b5a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1b5b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1b5c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b5d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1b5e0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1b5f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b600 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b620 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1b630 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1b640 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1b650 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b670 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1b680 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1b690 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1b6a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b6b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b6c0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1b6d0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1b6e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1b6f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b710 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1b720 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1b730 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1b740 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b760 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1b770 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1b780 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b7a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b7b0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1b7c0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1b7d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1b7e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b800 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1b810 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1b820 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b830 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b850 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1b860 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1b870 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1b880 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b8a0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1b8b0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1b8c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1b8d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b8f0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1b900 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1b910 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1b920 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b930 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b940 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1b950 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1b960 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1b970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b980 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1b990 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1b9a0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1b9b0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1b9c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b9d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1b9e0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1b9f0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1ba00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ba10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ba20 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1ba30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1ba40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ba50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ba60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ba70 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1ba80 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1ba90 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1baa0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1bab0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1bac0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1bad0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1bae0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1baf0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1bb00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bb10 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1bb20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1bb30 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1bb40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bb50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bb60 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1bb70 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1bb80 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1bb90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1bba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bbb0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1bbc0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1bbd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1bbe0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1bbf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1bc00 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1bc10 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1bc20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1bc30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1bc40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1bc50 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1bc60 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1bc70 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1bc80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bc90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bca0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1bcb0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1bcc0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1bcd0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1bce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bcf0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1bd00 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1bd10 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1bd20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1bd30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1bd40 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1bd50 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1bd60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1bd70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1bd80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1bd90 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1bda0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1bdb0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1bdc0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1bdd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1bde0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1bdf0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1be00 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1be10 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1be20 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1be30 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1be40 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1be50 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1be60 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1be70 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1be80 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1be90 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1bea0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1beb0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1bec0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1bed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1bee0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1bef0 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1bf00 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1bf10 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1bf20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1bf30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1bf40 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1bf50 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1bf60 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1bf70 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1bf80 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1bf90 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1bfa0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1bfb0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1bfc0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1bfd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1bfe0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1bff0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1c000 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1c010 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1c020 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1c030 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1c040 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1c050 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1c060 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1c070 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1c080 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1c090 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1c0a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1c0b0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1c0c0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1c0d0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1c0e0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1c0f0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1c100 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1c110 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1c120 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1c130 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1c140 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1c150 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1c160 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1c170 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1c180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1c190 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1c1a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1c1b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1c1c0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1c1d0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1c1e0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1c1f0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1c200 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1c210 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1c220 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1c230 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1c240 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1c250 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1c260 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1c270 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1c280 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1c290 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1c2a0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1c2b0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1c2c0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1c2d0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1c2e0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1c2f0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1c300 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1c310 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1c320 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1c330 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1c340 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1c350 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1c360 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1c370 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1c380 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1c390 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1c3a0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1c3b0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1c3c0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1c3d0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1c3e0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1c3f0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1c400 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1c410 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
1c420 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1c430 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1c440 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1c450 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1c460 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
1c470 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1c480 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1c490 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1c4a0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1c4b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1c4c0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1c4d0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1c4e0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1c4f0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
1c500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c510 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1c520 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
1c530 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
1c540 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
1c550 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
1c560 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
1c570 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
1c580 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1c590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1c5a0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
1c5b0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
1c5c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1c5d0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
1c5e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1c5f0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1c600 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1c610 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1c620 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1c630 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1c640 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
1c650 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
1c660 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
1c670 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1c680 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
1c690 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c6a0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
1c6b0 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
1c6c0 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1c6d0 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1c6e0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1c6f0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1c700 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1c710 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1c720 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1c730 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1c740 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1c750 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1c760 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1c770 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1c780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1c790 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1c7a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1c7b0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1c7c0 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1c7d0 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1c7e0 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1c7f0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1c800 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1c810 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1c820 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1c830 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1c840 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1c850 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1c860 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1c870 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1c880 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1c890 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1c8a0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1c8b0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1c8c0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1c8d0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1c8e0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1c8f0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1c900 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1c910 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1c920 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1c930 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1c940 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1c950 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c960 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c970 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1c980 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1c990 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1c9a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1c9b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1c9c0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1c9d0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1c9e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1c9f0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1ca00 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1ca10 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1ca20 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1ca30 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1ca40 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1ca50 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1ca60 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1ca70 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1ca80 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1ca90 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1caa0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1cab0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1cac0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1cad0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1cae0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1caf0 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1cb00 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1cb10 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1cb20 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1cb30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1cb40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1cb50 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1cb60 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1cb70 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1cb80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1cb90 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1cba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1cbb0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1cbc0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1cbd0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1cbe0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1cbf0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1cc00 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1cc10 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1cc20 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1cc30 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1cc40 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1cc50 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1cc60 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1cc70 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1cc80 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1cc90 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1cca0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1ccb0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1ccc0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1ccd0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1cce0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1ccf0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1cd00 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1cd10 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1cd20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1cd30 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1cd40 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1cd50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1cd60 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1cd70 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1cd80 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1cd90 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1cda0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1cdb0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1cdc0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1cdd0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1cde0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1cdf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1ce00 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1ce10 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1ce20 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1ce30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1ce40 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1ce50 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1ce60 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1ce70 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1ce80 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1ce90 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1cea0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1ceb0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1cec0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1ced0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1cee0 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1cef0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1cf00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cf10 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1cf20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1cf30 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1cf40 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1cf50 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1cf60 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1cf70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1cf80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1cf90 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1cfa0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1cfb0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1cfc0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1cfd0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1cfe0 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1cff0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1d000 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1d010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1d020 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1d030 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1d040 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1d050 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1d060 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1d070 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1d080 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1d090 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1d0a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1d0b0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1d0c0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1d0d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1d0e0 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
1d0f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1d100 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
1d110 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1d120 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
1d130 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1d140 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1d150 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1d160 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d170 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1d180 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1d190 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1d1a0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1d1b0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1d1c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1d1d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1d1e0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1d1f0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1d200 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1d210 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1d220 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1d230 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1d240 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1d250 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1d260 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1d270 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1d280 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1d290 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1d2a0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1d2b0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1d2c0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1d2d0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1d2e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1d2f0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d300 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1d310 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1d320 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1d330 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1d340 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1d350 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1d360 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
1d370 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1d380 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1d390 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1d3a0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1d3b0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1d3c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1d3d0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1d3e0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1d3f0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1d400 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1d410 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1d420 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1d430 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1d440 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1d450 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
1d460 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
1d470 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d480 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
1d490 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
1d4a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d4b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d4c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1d4d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1d4e0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1d4f0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1d500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d510 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1d520 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1d530 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1d540 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1d550 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1d560 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1d570 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1d580 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1d590 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1d5a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1d5b0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1d5c0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1d5d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d5e0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1d5f0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1d600 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1d610 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1d620 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1d630 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1d640 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1d650 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1d660 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1d670 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1d680 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1d690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d6a0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1d6b0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1d6c0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1d6d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1d6e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1d6f0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1d700 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1d710 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1d720 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1d730 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1d740 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1d750 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1d760 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1d770 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1d780 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1d790 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1d7a0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1d7b0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1d7c0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1d7d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d7e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1d7f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1d800 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1d810 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1d820 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1d830 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1d840 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1d850 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1d860 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1d870 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1d880 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1d890 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1d8a0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1d8b0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1d8c0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1d8d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1d8e0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1d8f0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1d900 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1d910 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1d920 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1d930 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1d940 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
1d950 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1d960 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
1d970 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1d980 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1d990 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
1d9a0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1d9b0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
1d9c0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
1d9d0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
1d9e0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
1d9f0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
1da00 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
1da10 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1da20 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
1da30 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
1da40 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
1da50 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
1da60 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
1da70 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
1da80 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
1da90 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
1daa0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
1dab0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
1dac0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1dad0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
1dae0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1daf0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
1db00 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
1db10 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
1db20 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
1db30 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1db40 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1db50 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1db60 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1db70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1db80 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1db90 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
1dba0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
1dbb0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
1dbc0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
1dbd0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
1dbe0 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
1dbf0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
1dc00 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
1dc10 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
1dc20 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
1dc30 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
1dc40 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
1dc50 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
1dc60 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
1dc70 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
1dc80 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
1dc90 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1dca0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
1dcb0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
1dcc0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1dcd0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
1dce0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
1dcf0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
1dd00 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
1dd10 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
1dd20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
1dd30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
1dd40 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
1dd50 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
1dd60 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
1dd70 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
1dd80 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
1dd90 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
1dda0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1ddb0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
1ddc0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
1ddd0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
1dde0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1ddf0 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
1de00 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
1de10 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
1de20 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
1de30 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
1de40 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
1de50 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1de60 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
1de70 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
1de80 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
1de90 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
1dea0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
1deb0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
1dec0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
1ded0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
1dee0 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
1def0 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
1df00 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
1df10 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
1df20 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
1df30 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
1df40 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
1df50 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
1df60 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
1df70 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
1df80 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
1df90 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
1dfa0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
1dfb0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
1dfc0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
1dfd0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
1dfe0 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
1dff0 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
1e000 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
1e010 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
1e020 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
1e030 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
1e040 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
1e050 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
1e060 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
1e070 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
1e080 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
1e090 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
1e0a0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
1e0b0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
1e0c0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
1e0d0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
1e0e0 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
1e0f0 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
1e100 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
1e110 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
1e120 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
1e130 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
1e140 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
1e150 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
1e160 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
1e170 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
1e180 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
1e190 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
1e1a0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
1e1b0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
1e1c0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
1e1d0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
1e1e0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
1e1f0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
1e200 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
1e210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
1e220 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
1e230 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
1e240 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
1e250 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
1e260 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1e270 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
1e280 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
1e290 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
1e2a0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
1e2b0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
1e2c0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
1e2d0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
1e2e0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1e2f0 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
1e300 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
1e310 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1e320 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
1e330 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
1e340 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
1e350 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
1e360 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
1e370 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
1e380 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
1e390 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
1e3a0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
1e3b0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
1e3c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1e3d0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
1e3e0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
1e3f0 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
1e400 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
1e410 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
1e420 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
1e430 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
1e440 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
1e450 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1e460 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1e470 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1e480 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
1e490 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
1e4a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1e4b0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
1e4c0 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20  o", "rw" or.**  
1e4d0 20 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70     "rwc". Attemp
1e4e0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
1e4f0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
1e500 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e  e is an error)^.
1e510 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
1e520 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
1e530 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1e540 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1e550 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
1e560 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
1e570 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
1e580 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
1e590 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
1e5a0 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
1e5b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1e5c0 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  to sqlite3_prepa
1e5d0 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  re_v2(). ^If the
1e5e0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
1e5f0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
1e600 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
1e610 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e620 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
1e630 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
1e640 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
1e650 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
1e660 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
1e670 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
1e680 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
1e690 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
1e6a0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
1e6b0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1e6c0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
1e6d0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
1e6e0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
1e6f0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
1e700 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1e710 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20  n_v2() is .**   
1e720 20 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e    used, it is an
1e730 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
1e740 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68  y a value for th
1e750 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
1e760 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20   that is .**    
1e770 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
1e780 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
1e790 69 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61  ified by the fla
1e7a0 67 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  gs passed as the
1e7b0 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70   third .**     p
1e7c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1e7d0 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
1e7e0 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
1e7f0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
1e800 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
1e810 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
1e820 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
1e830 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
1e840 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
1e850 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1e860 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
1e870 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1e880 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
1e890 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
1e8a0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
1e8b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
1e8c0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
1e8d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
1e8e0 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
1e8f0 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
1e900 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
1e910 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1e920 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
1e930 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
1e940 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
1e950 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
1e960 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
1e970 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
1e980 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
1e990 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
1e9a0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75  des any behaviou
1e9b0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
1e9c0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
1e9d0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1e9e0 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
1e9f0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1ea00 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
1ea10 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
1ea20 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
1ea30 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
1ea40 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1ea50 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
1ea60 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
1ea70 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1ea80 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
1ea90 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
1eaa0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
1eab0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
1eac0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
1ead0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
1eae0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
1eaf0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
1eb00 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
1eb10 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
1eb20 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
1eb30 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
1eb40 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
1eb50 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
1eb60 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
1eb70 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
1eb80 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
1eb90 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
1eba0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
1ebb0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1ebc0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
1ebd0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
1ebe0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
1ebf0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
1ec00 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
1ec10 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
1ec20 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
1ec30 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1ec40 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
1ec50 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
1ec60 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
1ec70 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
1ec80 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
1ec90 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1eca0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
1ecb0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
1ecc0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
1ecd0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1ece0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
1ecf0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
1ed00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
1ed10 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
1ed20 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
1ed30 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
1ed40 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
1ed50 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
1ed60 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
1ed70 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
1ed80 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
1ed90 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
1eda0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
1edb0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
1edc0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
1edd0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
1ede0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
1edf0 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
1ee00 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
1ee10 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
1ee20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
1ee30 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
1ee40 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
1ee50 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
1ee60 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
1ee70 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
1ee80 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
1ee90 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
1eea0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
1eeb0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
1eec0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
1eed0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
1eee0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
1eef0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
1ef00 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
1ef10 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
1ef20 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
1ef30 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
1ef40 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1ef50 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
1ef60 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
1ef70 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
1ef80 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
1ef90 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
1efa0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1efb0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1efc0 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
1efd0 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
1efe0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
1eff0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1f000 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
1f010 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
1f020 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
1f030 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
1f040 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
1f050 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
1f060 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
1f070 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
1f080 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
1f090 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
1f0a0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
1f0b0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
1f0c0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
1f0d0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
1f0e0 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
1f0f0 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
1f100 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
1f110 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
1f120 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
1f130 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
1f140 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
1f150 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
1f160 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
1f170 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
1f180 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
1f190 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
1f1a0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
1f1b0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
1f1c0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
1f1d0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
1f1e0 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
1f1f0 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
1f200 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
1f210 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
1f220 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
1f230 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
1f240 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
1f250 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
1f260 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
1f270 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
1f280 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
1f290 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
1f2a0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
1f2b0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
1f2c0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
1f2d0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1f2e0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1f2f0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1f300 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1f310 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1f320 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1f330 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1f340 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1f350 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1f360 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1f370 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1f380 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1f390 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1f3a0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1f3b0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1f3c0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1f3d0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1f3e0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1f3f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1f400 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1f410 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
1f420 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
1f430 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1f440 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1f450 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1f460 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1f470 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1f480 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1f490 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1f4a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1f4b0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
1f4c0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
1f4d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1f4e0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
1f4f0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1f500 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1f510 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1f520 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1f530 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
1f540 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1f550 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1f560 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1f570 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1f580 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
1f590 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1f5a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1f5b0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
1f5c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
1f5d0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
1f5e0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
1f5f0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
1f600 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
1f610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f620 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
1f630 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
1f640 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ters.**.** This 
1f650 69 73 20 61 20 75 74 69 6c 69 74 79 20 72 6f 75  is a utility rou
1f660 74 69 6e 65 2c 20 75 73 65 66 75 6c 20 74 6f 20  tine, useful to 
1f670 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1f680 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 73  ons, that checks
1f690 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
1f6a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
1f6b0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
1f6c0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
1f6d0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
1f6e0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
1f6f0 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
1f700 75 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ue of the query 
1f710 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1f720 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61   The zFilename a
1f730 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 66  rgument is the f
1f740 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
1f750 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
1f760 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74 68 6f  xOpen().** metho
1f770 64 20 6f 66 20 61 20 56 46 53 20 69 6d 70 6c 65  d of a VFS imple
1f780 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 20  mentation.  The 
1f790 7a 50 61 72 61 6d 20 61 72 67 75 6d 65 6e 74 20  zParam argument 
1f7a0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1f7b0 68 65 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  he.** query para
1f7c0 6d 65 74 65 72 20 77 65 20 73 65 65 6b 2e 20 20  meter we seek.  
1f7d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1f7e0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
1f7f0 66 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a 2a 20  f the zParam.** 
1f800 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
1f810 65 78 69 73 74 73 2e 20 20 49 66 20 74 68 65 20  exists.  If the 
1f820 70 61 72 61 6d 65 74 65 72 20 64 6f 65 73 20 6e  parameter does n
1f830 6f 74 20 65 78 69 73 74 2c 20 74 68 69 73 20 72  ot exist, this r
1f840 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e  outine.** return
1f850 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f860 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 7a  ..**.** If the z
1f870 46 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  Filename argumen
1f880 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  t to this functi
1f890 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  on is not a poin
1f8a0 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 0a  ter that SQLite.
1f8b0 2a 2a 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  ** passed into t
1f8c0 68 65 20 78 4f 70 65 6e 20 56 46 53 20 6d 65 74  he xOpen VFS met
1f8d0 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
1f8e0 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
1f8f0 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64  outine.** is und
1f900 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
1f910 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
1f920 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f930 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
1f940 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
1f950 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
1f960 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
1f970 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1f980 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
1f990 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
1f9a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f9b0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1f9c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1f9d0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1f9e0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1f9f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1fa00 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1fa10 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1fa20 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1fa30 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1fa40 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1fa50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1fa60 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1fa70 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1fa80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1fa90 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1faa0 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1fab0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1fac0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1fad0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
1fae0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1faf0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
1fb00 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
1fb10 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
1fb20 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
1fb30 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
1fb40 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1fb50 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
1fb60 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1fb70 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
1fb80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1fb90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1fba0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1fbb0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1fbc0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1fbd0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1fbe0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1fbf0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1fc00 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1fc10 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
1fc20 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1fc30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1fc40 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1fc50 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1fc60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1fc70 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1fc80 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1fc90 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1fca0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1fcb0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1fcc0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1fcd0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1fce0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1fcf0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1fd00 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1fd10 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
1fd20 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
1fd30 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1fd40 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
1fd50 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
1fd60 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
1fd70 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
1fd80 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
1fd90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
1fda0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
1fdb0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
1fdc0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
1fdd0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
1fde0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
1fdf0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
1fe00 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
1fe10 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
1fe20 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
1fe30 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
1fe40 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
1fe50 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
1fe60 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
1fe70 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
1fe80 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
1fe90 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
1fea0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1feb0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
1fec0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1fed0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
1fee0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1fef0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
1ff00 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
1ff10 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
1ff20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
1ff30 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
1ff40 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
1ff50 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
1ff60 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
1ff70 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
1ff80 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
1ff90 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1ffa0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1ffb0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1ffc0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1ffd0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1ffe0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1fff0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
20000 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
20010 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
20020 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
20030 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
20040 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
20050 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
20060 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
20070 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
20080 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
20090 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
200a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
200b0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
200c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
200d0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
200e0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
200f0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
20100 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
20110 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
20120 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
20130 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20140 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
20150 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
20160 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
20170 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
20180 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
20190 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
201a0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
201b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
201c0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
201d0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
201e0 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
201f0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
20200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
20210 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
20220 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
20230 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
20240 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
20250 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
20260 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
20270 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20280 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
20290 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
202a0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
202b0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
202c0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
202d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
202e0 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
202f0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
20300 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
20310 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
20320 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
20330 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
20340 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
20350 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
20360 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20370 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
20380 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
20390 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
203a0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
203b0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
203c0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
203d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
203e0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
203f0 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
20400 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
20410 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
20420 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
20430 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
20440 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
20450 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
20460 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
20470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20480 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
20490 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
204a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
204b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
204c0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
204d0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
204e0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
204f0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
20500 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
20510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
20520 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
20530 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
20540 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
20550 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
20560 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
20570 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
20580 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
20590 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
205a0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
205b0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
205c0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
205d0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
205e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
205f0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
20600 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
20610 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
20620 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
20630 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
20640 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
20650 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
20660 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
20670 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
20680 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
20690 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
206a0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
206b0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
206c0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
206d0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
206e0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
206f0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
20700 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
20710 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
20720 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
20730 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
20740 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
20750 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
20760 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
20770 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
20780 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
20790 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
207a0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
207b0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
207c0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
207d0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
207e0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
207f0 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
20800 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
20810 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
20820 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
20830 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
20840 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
20850 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
20860 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
20870 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
20880 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
20890 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
208a0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
208b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
208c0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
208d0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
208e0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
208f0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
20900 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
20910 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
20920 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
20930 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
20940 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
20950 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
20960 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
20970 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
20980 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
20990 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
209a0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
209b0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
209c0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
209d0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
209e0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
209f0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
20a00 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
20a10 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
20a20 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
20a30 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
20a40 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
20a50 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
20a60 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
20a70 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
20a80 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
20a90 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
20aa0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
20ab0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
20ac0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
20ad0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
20ae0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
20af0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
20b00 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
20b10 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
20b20 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
20b30 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20b40 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
20b50 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
20b60 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
20b70 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
20b80 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
20b90 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
20ba0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
20bb0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
20bc0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
20bd0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
20be0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
20bf0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
20c00 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
20c10 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
20c20 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
20c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
20c40 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
20c50 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
20c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20c70 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
20c80 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
20c90 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
20ca0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
20cb0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
20cc0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
20cd0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
20ce0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
20cf0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
20d00 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
20d10 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
20d20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
20d30 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
20d40 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
20d50 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
20d60 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
20d70 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
20d80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
20d90 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
20da0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
20db0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
20dc0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
20dd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
20de0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
20df0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
20e00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20e10 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
20e20 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
20e30 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
20e40 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
20e50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
20e60 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
20e70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
20e80 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
20e90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20ea0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
20eb0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
20ec0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
20ed0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
20ee0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
20ef0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
20f00 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
20f10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20f20 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
20f30 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
20f40 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
20f50 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
20f60 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
20f70 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
20f80 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
20f90 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
20fa0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
20fb0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
20fc0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
20fd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
20fe0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
20ff0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
21000 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
21010 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21020 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
21030 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
21040 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
21050 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
21060 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
21070 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
21080 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
21090 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
210a0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
210b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
210c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
210d0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
210e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
210f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21100 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
21110 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
21120 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
21130 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
21140 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
21150 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
21160 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
21170 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
21180 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
21190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
211a0 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
211b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
211c0 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
211d0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
211e0 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
211f0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
21200 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
21210 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
21220 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
21230 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
21240 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
21250 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
21260 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
21270 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
21280 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
21290 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
212a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
212b0 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
212c0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
212d0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
212e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
212f0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
21300 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
21310 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
21320 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21330 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
21340 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
21350 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
21360 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
21370 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21380 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
21390 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
213a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
213b0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
213c0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
213d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
213e0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
213f0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
21400 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
21410 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
21420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21430 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
21440 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
21450 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
21460 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
21470 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
21480 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
21490 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
214a0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
214b0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
214c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
214d0 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
214e0 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
214f0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
21500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21510 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
21520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21530 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
21540 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
21550 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
21560 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
21570 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
21580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21590 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
215a0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
215b0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
215c0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
215d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
215e0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
215f0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
21600 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
21610 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
21620 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
21630 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
21640 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
21650 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
21660 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
21670 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
21680 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
21690 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
216a0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
216b0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
216c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
216d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
216e0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
216f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21700 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
21710 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
21720 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
21730 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
21740 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
21750 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
21760 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
21770 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
21780 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
21790 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
217a0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
217b0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
217c0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
217d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
217e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
217f0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
21800 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
21810 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
21820 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
21830 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
21840 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
21850 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
21860 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
21870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
21880 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
21890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
218a0 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
218b0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
218c0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
218d0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
218e0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
218f0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
21900 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
21910 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
21920 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
21930 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
21940 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21950 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
21960 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
21970 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21980 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
21990 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
219a0 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
219b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
219c0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
219d0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
219e0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
219f0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
21a00 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
21a10 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
21a20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21a30 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
21a40 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
21a50 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
21a60 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
21a70 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
21a80 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
21a90 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
21aa0 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
21ab0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
21ac0 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
21ad0 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
21ae0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
21af0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
21b00 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
21b10 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
21b20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
21b30 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
21b40 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
21b50 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
21b60 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
21b70 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
21b80 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
21b90 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
21ba0 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
21bb0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
21bc0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
21bd0 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
21be0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
21bf0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
21c00 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
21c10 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
21c20 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
21c30 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
21c40 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
21c50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
21c60 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
21c70 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
21c80 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
21c90 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
21ca0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
21cb0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
21cc0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
21cd0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
21ce0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
21cf0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
21d00 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
21d10 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
21d20 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
21d30 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
21d40 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
21d50 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
21d60 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
21d70 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
21d80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
21d90 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
21da0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
21db0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
21dc0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
21dd0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
21de0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
21df0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
21e00 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
21e10 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
21e20 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
21e30 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
21e40 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
21e50 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
21e60 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
21e70 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
21e80 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
21e90 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
21ea0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
21eb0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
21ec0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21ed0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
21ee0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
21ef0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
21f00 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
21f10 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
21f20 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
21f30 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
21f40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
21f50 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
21f60 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
21f70 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
21f80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
21f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21fa0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
21fb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
21fc0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
21fd0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
21fe0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
21ff0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
22000 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
22010 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
22020 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
22030 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
22040 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
22050 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
22060 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
22070 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
22080 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
22090 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
220a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
220b0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
220c0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
220d0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
220e0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
220f0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
22100 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
22110 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
22120 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
22130 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
22140 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
22150 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
22160 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
22170 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
22180 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
22190 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
221a0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
221b0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
221c0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
221d0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
221e0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
221f0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
22200 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
22210 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
22220 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
22230 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
22240 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
22250 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
22260 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
22270 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
22280 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
22290 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
222a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
222b0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
222c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
222d0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
222e0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
222f0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
22300 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
22310 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
22320 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
22330 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
22340 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22350 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
22360 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
22370 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
22380 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
22390 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
223a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
223b0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
223c0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
223d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
223e0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
223f0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
22400 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
22410 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
22420 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
22430 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
22440 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
22450 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
22460 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
22470 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
22480 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
22490 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
224a0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
224b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
224c0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
224d0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
224e0 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
224f0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
22500 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
22510 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
22520 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
22530 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
22540 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
22550 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
22560 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
22570 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
22580 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
22590 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
225a0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
225b0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
225c0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
225d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
225e0 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
225f0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
22600 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
22610 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
22620 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
22630 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
22640 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
22650 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
22660 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
22670 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
22680 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
22690 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
226a0 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
226b0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
226c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
226d0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
226e0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
226f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
22700 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
22710 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
22720 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22730 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
22740 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
22750 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
22760 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
22770 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
22780 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
22790 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
227a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
227b0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
227c0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
227d0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
227e0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
227f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22800 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
22810 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
22820 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22830 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
22840 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22850 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22860 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
22870 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
22880 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
22890 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
228a0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
228b0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
228c0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
228d0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
228e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
228f0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
22900 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
22910 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
22920 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
22930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
22940 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
22950 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
22960 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
22970 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22980 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
22990 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
229a0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
229b0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
229c0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
229d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
229e0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
229f0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
22a00 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
22a10 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
22a20 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
22a30 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
22a40 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22a50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
22a60 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
22a70 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
22a80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22a90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
22aa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
22ab0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
22ac0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
22ad0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
22ae0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
22af0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
22b00 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
22b10 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
22b20 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
22b30 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
22b40 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
22b50 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
22b60 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
22b70 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
22b80 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
22b90 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
22ba0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
22bb0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
22bc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22bd0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
22be0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
22bf0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
22c00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
22c10 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
22c20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
22c30 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
22c40 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
22c50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
22c60 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
22c70 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
22c80 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
22c90 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
22ca0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
22cb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22cc0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
22cd0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
22ce0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
22cf0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
22d00 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
22d10 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
22d20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
22d30 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
22d40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22d50 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
22d60 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
22d70 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
22d80 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
22d90 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
22da0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
22db0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
22dc0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
22dd0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
22de0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
22df0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
22e00 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
22e10 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
22e20 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
22e30 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
22e40 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
22e50 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
22e60 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
22e70 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
22e80 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
22e90 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
22ea0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
22eb0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
22ec0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
22ed0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
22ee0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
22ef0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
22f00 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
22f10 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
22f20 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
22f30 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
22f40 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
22f50 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
22f60 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
22f70 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
22f80 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
22f90 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
22fa0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
22fb0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
22fc0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
22fd0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
22fe0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
22ff0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
23000 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
23010 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
23020 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
23030 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
23040 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
23050 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
23060 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
23070 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
23080 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
23090 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
230a0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
230b0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
230c0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
230d0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
230e0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
230f0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
23100 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
23110 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
23120 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
23130 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
23140 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
23150 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
23160 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
23170 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
23180 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
23190 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
231a0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
231b0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
231c0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
231d0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
231e0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
231f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
23200 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
23210 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
23220 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
23230 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
23240 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
23250 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
23260 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
23270 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
23280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
23290 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
232a0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
232b0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
232c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
232d0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
232e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
232f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
23300 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
23310 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
23320 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
23330 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
23340 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
23350 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
23360 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
23370 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
23380 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
23390 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
233a0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
233b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
233c0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
233d0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
233e0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
233f0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
23400 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
23410 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
23420 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
23430 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
23440 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
23450 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
23460 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
23470 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23480 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
23490 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
234a0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
234b0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
234c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
234d0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
234e0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
234f0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
23500 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
23510 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
23520 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
23530 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
23540 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23550 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
23560 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
23570 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
23580 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
23590 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
235a0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
235b0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
235c0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
235d0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
235e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
235f0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
23600 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
23610 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
23620 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
23630 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
23640 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
23650 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
23660 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
23670 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
23680 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
23690 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
236a0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
236b0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
236c0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
236d0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
236e0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
236f0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
23700 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
23710 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
23720 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
23730 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
23740 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
23750 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
23760 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
23770 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
23780 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
23790 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
237a0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
237b0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
237c0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
237d0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
237e0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
237f0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
23800 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
23810 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
23820 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
23830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23840 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
23850 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
23860 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
23870 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
23880 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
23890 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
238a0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
238b0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
238c0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
238d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
238e0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
238f0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
23900 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23910 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
23920 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
23930 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
23940 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
23950 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
23960 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
23970 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
23980 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
23990 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
239a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
239b0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
239c0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
239d0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
239e0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
239f0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
23a00 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
23a10 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
23a20 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23a30 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
23a40 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
23a50 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
23a60 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
23a70 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
23a80 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
23a90 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
23aa0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
23ab0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
23ac0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
23ad0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
23ae0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
23af0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
23b00 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
23b10 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
23b20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
23b30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
23b40 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
23b50 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
23b60 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
23b70 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
23b80 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
23b90 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
23ba0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
23bb0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
23bc0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
23bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
23be0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
23bf0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
23c00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
23c10 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
23c20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
23c30 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
23c40 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
23c50 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
23c60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
23c70 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
23c80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
23c90 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
23ca0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
23cb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
23cc0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
23cd0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
23ce0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
23cf0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
23d00 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23d10 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
23d20 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
23d30 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
23d40 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
23d50 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
23d60 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
23d70 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
23d80 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
23d90 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
23da0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23db0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
23dc0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
23dd0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
23de0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
23df0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
23e00 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
23e10 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
23e20 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
23e30 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
23e40 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
23e50 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
23e60 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
23e70 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
23e80 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
23e90 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
23ea0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
23eb0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
23ec0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
23ed0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
23ee0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
23ef0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
23f00 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
23f10 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
23f20 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
23f30 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
23f40 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
23f50 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
23f60 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
23f70 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
23f80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
23f90 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
23fa0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
23fb0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
23fc0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
23fd0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
23fe0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
23ff0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
24000 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24010 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
24020 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
24030 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
24040 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
24050 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
24060 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
24070 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
24080 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
24090 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
240a0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
240b0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
240c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
240d0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
240e0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
240f0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
24100 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
24110 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
24120 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
24130 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
24140 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
24150 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
24160 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
24170 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
24180 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
24190 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
241a0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
241b0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
241c0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
241d0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
241e0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
241f0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
24200 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
24210 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
24220 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
24230 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
24240 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
24250 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
24260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
24270 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
24280 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
24290 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
242a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
242b0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
242c0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
242d0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
242e0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
242f0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
24300 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
24310 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
24320 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
24330 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
24340 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
24350 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
24360 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
24370 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
24380 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
24390 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
243a0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
243b0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
243c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
243d0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
243e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
243f0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
24400 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
24410 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
24420 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
24430 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
24440 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
24450 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
24460 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
24470 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
24480 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
24490 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
244a0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
244b0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
244c0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
244d0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
244e0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
244f0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
24500 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
24510 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
24520 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
24530 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
24540 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
24550 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
24560 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
24570 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
24580 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
24590 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
245a0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
245b0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
245c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
245d0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
245e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
245f0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
24600 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
24610 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
24620 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
24630 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
24640 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
24650 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
24660 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
24670 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
24680 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
24690 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
246a0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
246b0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
246c0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
246d0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
246e0 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
246f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24700 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
24710 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
24720 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
24730 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
24740 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
24750 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
24760 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
24770 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
24780 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
24790 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
247a0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
247b0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
247c0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
247d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
247e0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
247f0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
24800 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
24810 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
24820 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
24830 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
24840 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
24850 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
24860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
24870 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
24880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24890 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
248a0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
248b0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
248c0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
248d0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
248e0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
248f0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
24900 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
24910 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
24920 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
24930 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
24940 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
24950 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
24960 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
24970 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
24980 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
24990 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
249a0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
249b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
249c0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
249d0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
249e0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
249f0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
24a00 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
24a10 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
24a20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
24a30 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
24a40 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
24a50 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
24a60 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
24a70 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
24a80 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
24a90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24aa0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
24ab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
24ac0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
24ad0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
24ae0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
24af0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
24b00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24b10 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
24b20 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
24b30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
24b40 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
24b50 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
24b60 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
24b70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24b80 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
24b90 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
24ba0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
24bb0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
24bc0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
24bd0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
24be0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
24bf0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
24c00 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
24c10 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
24c20 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
24c30 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
24c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24c50 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
24c60 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
24c70 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
24c80 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
24c90 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
24ca0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
24cb0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
24cc0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
24cd0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
24ce0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
24cf0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
24d00 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
24d10 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
24d20 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
24d30 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
24d40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24d50 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
24d60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24d70 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
24d80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
24d90 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
24da0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
24db0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
24dc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24dd0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
24de0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
24df0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
24e00 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
24e10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24e20 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
24e30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
24e40 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
24e50 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
24e60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
24e70 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
24e80 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
24e90 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
24ea0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
24eb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
24ec0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
24ed0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
24ee0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
24ef0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
24f00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
24f10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24f20 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
24f30 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
24f40 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
24f50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
24f60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24f70 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
24f80 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
24f90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
24fa0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
24fb0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
24fc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
24fd0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
24fe0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
24ff0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
25000 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
25010 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
25020 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
25030 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
25040 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
25050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25060 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
25070 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
25080 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
25090 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
250a0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
250b0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
250c0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
250d0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
250e0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
250f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
25100 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
25110 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
25120 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
25130 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
25140 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
25150 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
25160 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
25170 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
25180 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
25190 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
251a0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
251b0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
251c0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
251d0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
251e0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
251f0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
25200 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
25210 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
25220 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
25230 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
25240 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
25250 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
25260 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
25270 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
25280 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
25290 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
252a0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
252b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
252c0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
252d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
252e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
252f0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
25300 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
25310 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
25320 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
25330 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
25340 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
25350 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
25360 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
25370 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
25380 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
25390 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
253a0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
253b0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
253c0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
253d0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
253e0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
253f0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
25400 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
25410 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
25420 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
25430 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
25440 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
25450 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
25460 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
25470 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
25480 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
25490 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
254a0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
254b0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
254c0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
254d0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
254e0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
254f0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
25500 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
25510 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
25520 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
25530 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
25540 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
25550 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
25560 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
25570 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
25580 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
25590 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
255a0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
255b0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
255c0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
255d0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
255e0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
255f0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
25600 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
25610 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
25620 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
25630 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
25640 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
25650 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
25660 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
25670 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
25680 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
25690 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
256a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
256b0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
256c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
256d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
256e0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
256f0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
25700 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
25710 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25720 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25730 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
25740 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
25750 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
25760 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
25770 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
25780 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
25790 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
257a0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
257b0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
257c0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
257d0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
257e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
257f0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
25800 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
25810 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
25820 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
25830 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
25840 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
25850 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
25860 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
25870 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
25880 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
25890 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
258a0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
258b0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
258c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
258d0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
258e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
258f0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
25900 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
25910 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25920 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
25930 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
25940 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
25950 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
25960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25970 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
25980 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
25990 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
259a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
259b0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
259c0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
259d0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
259e0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
259f0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
25a00 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
25a10 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
25a20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
25a30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
25a40 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
25a50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25a60 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
25a70 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
25a80 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
25a90 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
25aa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25ab0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25ac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
25ad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25ae0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
25af0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
25b00 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
25b10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
25b20 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
25b30 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
25b40 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
25b50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25b60 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
25b70 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
25b80 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
25b90 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
25ba0 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
25bb0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
25bc0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
25bd0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25be0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
25bf0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
25c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
25c10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
25c20 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25c30 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
25c40 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
25c50 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
25c60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
25c70 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
25c80 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
25c90 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
25ca0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
25cb0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
25cc0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
25cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
25ce0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
25cf0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
25d00 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
25d10 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
25d20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
25d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
25d40 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
25d50 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
25d60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
25d70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
25d80 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
25d90 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
25da0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25db0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
25dc0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
25dd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
25de0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
25df0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
25e00 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
25e10 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
25e20 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
25e30 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
25e40 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
25e50 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
25e60 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
25e70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
25e80 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
25e90 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
25ea0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
25eb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
25ec0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
25ed0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
25ee0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
25ef0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
25f00 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
25f10 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
25f20 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
25f30 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
25f40 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
25f50 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
25f60 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
25f70 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
25f80 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
25f90 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
25fa0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
25fb0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
25fc0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
25fd0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
25fe0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
25ff0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
26000 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
26010 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
26020 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
26030 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
26040 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
26050 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
26060 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
26070 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
26080 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
26090 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
260a0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
260b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
260c0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
260d0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
260e0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
260f0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
26100 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
26110 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
26120 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
26130 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
26140 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
26150 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
26160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26170 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
26180 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
26190 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
261a0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
261b0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
261c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
261d0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
261e0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
261f0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
26200 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
26210 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
26220 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
26230 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
26240 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
26250 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
26260 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
26270 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
26280 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
26290 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
262a0 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
262b0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
262c0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
262d0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
262e0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
262f0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
26300 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
26310 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
26320 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
26330 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
26340 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
26350 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
26360 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
26370 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
26380 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
26390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
263a0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
263b0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
263c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
263d0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
263e0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
263f0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
26400 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
26410 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26420 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
26430 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
26440 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
26450 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
26460 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
26470 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
26480 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
26490 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
264a0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
264b0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
264c0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
264d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
264e0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
264f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26500 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
26510 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
26520 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
26530 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
26540 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
26550 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
26560 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
26570 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
26580 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
26590 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
265a0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
265b0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
265c0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
265d0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
265e0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
265f0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
26600 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
26610 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
26620 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
26630 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
26640 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
26650 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
26660 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
26670 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
26680 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
26690 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
266a0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
266b0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
266c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
266d0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
266e0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
266f0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
26700 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
26710 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
26720 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
26730 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
26740 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
26750 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
26760 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
26770 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
26780 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
26790 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
267a0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
267b0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
267c0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
267d0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
267e0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
267f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
26800 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
26810 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
26820 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
26830 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
26840 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
26850 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
26860 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
26870 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
26880 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
26890 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
268a0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
268b0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
268c0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
268d0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
268e0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
268f0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
26900 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
26910 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26920 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
26930 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
26940 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
26950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
26960 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
26970 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
26980 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
26990 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
269a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
269b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
269c0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
269d0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
269e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
269f0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
26a00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26a10 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
26a20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26a30 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
26a40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
26a50 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
26a60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
26a70 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26a80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
26a90 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
26aa0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
26ab0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26ac0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
26ad0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26ae0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
26af0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
26b00 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
26b10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26b20 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
26b30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
26b40 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
26b50 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
26b60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26b70 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
26b80 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
26b90 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
26ba0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26bb0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
26bc0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
26bd0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
26be0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
26bf0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
26c00 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
26c10 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
26c20 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
26c30 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
26c40 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
26c50 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
26c60 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
26c70 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
26c80 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
26c90 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
26ca0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
26cb0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
26cc0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
26cd0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
26ce0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
26cf0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
26d00 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
26d10 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
26d20 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
26d30 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
26d40 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
26d50 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
26d60 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
26d70 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
26d80 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
26d90 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
26da0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
26db0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
26dc0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
26dd0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
26de0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
26df0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
26e00 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
26e10 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
26e20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
26e30 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
26e40 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
26e50 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
26e60 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
26e70 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
26e80 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
26e90 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
26ea0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
26eb0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
26ec0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
26ed0 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
26ee0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
26ef0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
26f00 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
26f10 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
26f20 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
26f30 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
26f40 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
26f50 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
26f60 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
26f70 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
26f80 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
26f90 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
26fa0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
26fb0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
26fc0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
26fd0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
26fe0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
26ff0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27000 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
27010 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
27020 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
27030 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
27040 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
27050 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
27060 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27070 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
27080 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
27090 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
270a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
270b0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
270c0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
270d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
270e0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
270f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
27100 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
27110 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
27120 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
27130 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
27140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27150 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
27160 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
27170 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
27180 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
27190 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
271a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
271b0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
271c0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
271d0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
271e0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
271f0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
27200 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
27210 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
27220 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
27230 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
27240 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
27250 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27260 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
27270 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
27280 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
27290 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
272a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
272b0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
272c0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
272d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
272e0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
272f0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
27300 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
27310 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
27320 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
27330 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
27340 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
27350 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
27360 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
27370 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
27380 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
27390 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
273a0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
273b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
273c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
273d0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
273e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
273f0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
27400 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
27410 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
27420 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
27430 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
27440 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
27450 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
27460 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
27470 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
27480 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
27490 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
274a0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
274b0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
274c0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
274d0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
274e0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
274f0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
27500 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
27510 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
27520 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
27530 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
27540 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
27550 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
27560 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
27570 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
27580 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
27590 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
275a0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
275b0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
275c0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
275d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
275e0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
275f0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
27600 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
27610 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
27620 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
27630 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
27640 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
27650 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
27660 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
27670 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
27680 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
27690 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
276a0 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
276b0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
276c0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
276d0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
276e0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
276f0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
27700 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
27710 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
27720 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
27730 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
27740 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
27750 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
27760 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
27770 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
27780 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
27790 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
277a0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
277b0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
277c0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
277d0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
277e0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
277f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
27800 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
27810 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
27820 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
27830 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
27840 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
27850 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
27860 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
27870 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
27880 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
27890 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
278a0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
278b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
278c0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
278d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
278e0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
278f0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
27900 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
27910 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
27920 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
27930 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
27940 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
27950 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
27960 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
27970 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
27980 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
27990 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
279a0 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
279b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
279c0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
279d0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
279e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
279f0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
27a00 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
27a10 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
27a20 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
27a30 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
27a40 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
27a50 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
27a60 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
27a70 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
27a80 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
27a90 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
27aa0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
27ab0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
27ac0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
27ad0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
27ae0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
27af0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
27b00 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
27b10 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
27b20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
27b30 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
27b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
27b50 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
27b60 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
27b70 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
27b80 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
27b90 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
27ba0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
27bb0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
27bc0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
27bd0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
27be0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
27bf0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
27c00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
27c10 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
27c20 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
27c30 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
27c40 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
27c50 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
27c60 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
27c70 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
27c80 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
27c90 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
27ca0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
27cb0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
27cc0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
27cd0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
27ce0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
27cf0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
27d00 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
27d10 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
27d20 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
27d30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
27d40 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
27d50 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
27d60 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
27d70 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
27d80 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
27d90 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
27da0 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
27db0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
27dc0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
27dd0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
27de0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
27df0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
27e00 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
27e10 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
27e20 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
27e30 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
27e40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
27e50 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
27e60 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
27e70 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
27e80 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
27e90 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
27ea0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
27eb0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
27ec0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
27ed0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
27ee0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
27ef0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
27f00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
27f10 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
27f20 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
27f30 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
27f40 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
27f50 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
27f60 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
27f70 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
27f80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27f90 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
27fa0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
27fb0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
27fc0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
27fd0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
27fe0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
27ff0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
28000 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
28010 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
28020 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
28030 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
28040 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
28050 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
28060 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
28070 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
28080 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
28090 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
280a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
280b0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
280c0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
280d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
280e0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
280f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
28100 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
28110 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
28120 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
28130 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
28140 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
28150 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
28160 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
28170 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
28180 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
28190 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
281a0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
281b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
281c0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
281d0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
281e0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
281f0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
28200 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
28210 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
28220 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
28230 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
28240 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
28250 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
28260 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
28270 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
28280 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
28290 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
282a0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
282b0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
282c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
282d0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
282e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
282f0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
28300 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
28310 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
28320 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
28330 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
28340 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
28350 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
28360 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
28370 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
28380 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
28390 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
283a0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
283b0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
283c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
283d0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
283e0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
283f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
28400 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
28410 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
28420 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
28430 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
28440 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
28450 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
28460 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
28470 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
28480 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
28490 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
284a0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
284b0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
284c0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
284d0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
284e0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
284f0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
28500 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
28510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
28520 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
28530 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
28540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28550 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
28560 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
28570 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
28580 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
28590 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
285a0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
285b0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
285c0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
285d0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
285e0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
285f0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
28600 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
28610 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
28620 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
28630 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
28640 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
28650 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
28660 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
28670 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
28680 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
28690 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
286a0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
286b0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
286c0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
286d0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
286e0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
286f0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
28700 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
28710 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
28720 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
28730 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
28740 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
28750 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
28760 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
28770 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
28780 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
28790 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
287a0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
287b0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
287c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
287d0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
287e0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
287f0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
28800 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
28810 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
28820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
28830 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
28840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
28850 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
28860 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
28870 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
28880 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
28890 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
288a0 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
288b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
288c0 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
288d0 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
288e0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
288f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
28900 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
28910 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
28920 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
28930 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
28940 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
28950 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
28960 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
28970 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
28980 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
28990 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
289a0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
289b0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
289c0 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
289d0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
289e0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
289f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
28a00 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
28a10 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
28a20 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
28a30 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
28a40 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
28a50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
28a60 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
28a70 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
28a80 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
28a90 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
28aa0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
28ab0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
28ac0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
28ad0 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
28ae0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
28af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
28b00 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
28b10 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
28b20 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
28b30 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
28b40 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
28b50 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
28b60 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
28b70 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
28b80 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
28b90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
28ba0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
28bb0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
28bc0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
28bd0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
28be0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
28bf0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
28c00 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
28c10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28c20 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
28c30 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
28c40 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
28c50 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
28c60 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
28c70 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
28c80 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
28c90 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
28ca0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
28cb0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
28cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
28cd0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
28ce0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
28cf0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
28d00 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28d10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
28d20 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
28d30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
28d40 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
28d50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
28d60 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
28d70 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
28d80 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
28d90 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
28da0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
28db0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
28dc0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
28dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28de0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28df0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
28e00 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
28e10 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
28e20 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
28e30 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
28e40 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
28e50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
28e60 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
28e70 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
28e80 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
28e90 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
28ea0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
28eb0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
28ec0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
28ed0 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
28ee0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
28ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
28f00 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
28f10 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
28f20 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
28f30 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
28f40 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
28f50 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
28f60 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
28f70 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
28f80 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28f90 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
28fa0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
28fb0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
28fc0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
28fd0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
28fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28ff0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
29000 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
29010 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
29020 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
29030 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
29040 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
29050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29060 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
29070 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
29080 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
29090 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
290a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
290b0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
290c0 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
290d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
290e0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
290f0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
29100 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
29110 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
29120 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
29130 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
29140 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
29150 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
29160 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
29170 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
29180 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
29190 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
291a0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
291b0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
291c0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
291d0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
291e0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
291f0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
29200 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
29210 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
29220 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
29230 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
29240 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
29250 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
29260 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
29270 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
29280 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
29290 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
292a0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
292b0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
292c0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
292d0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
292e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
292f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
29300 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
29310 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
29320 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
29330 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29340 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
29350 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
29360 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
29370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29380 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
29390 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
293a0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
293b0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
293c0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
293d0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
293e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
293f0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
29400 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
29410 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
29420 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
29430 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
29440 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
29450 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
29460 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
29470 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
29480 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
29490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
294a0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
294b0 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
294c0 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
294d0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
294e0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
294f0 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
29500 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
29510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29520 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
29530 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
29540 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
29550 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
29560 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
29570 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
29580 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
29590 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
295a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
295b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
295c0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
295d0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
295e0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
295f0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
29600 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o terminated.  ^
29610 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
29620 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
29630 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
29640 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
29650 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
29660 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
29670 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
29680 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
29690 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
296a0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
296b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
296c0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
296d0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
296e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
296f0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
29700 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
29710 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
29720 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
29730 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
29740 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
29750 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29760 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
29770 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
29780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
29790 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
297a0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
297b0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
297c0 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
297d0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
297e0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
297f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
29800 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
29810 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
29820 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
29830 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
29840 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
29850 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
29860 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
29870 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
29880 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
29890 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
298a0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
298b0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
298c0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
298d0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
298e0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
298f0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
29900 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
29910 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
29920 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
29930 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
29940 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
29950 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
29960 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
29970 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
29980 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
29990 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
299a0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
299b0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
299c0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
299d0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
299e0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
299f0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
29a00 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
29a10 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
29a20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
29a30 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
29a40 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
29a50 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
29a60 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
29a70 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
29a80 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
29a90 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
29aa0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
29ab0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
29ac0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
29ad0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
29ae0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
29af0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
29b00 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
29b10 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
29b20 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
29b30 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
29b40 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
29b50 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
29b60 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
29b70 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
29b80 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
29b90 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
29ba0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
29bb0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
29bc0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
29bd0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
29be0 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
29bf0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
29c00 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
29c10 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
29c20 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
29c30 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
29c40 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
29c50 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
29c60 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
29c70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
29c80 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
29c90 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
29ca0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
29cb0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
29cc0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
29cd0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
29ce0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
29cf0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
29d00 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
29d10 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
29d20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
29d30 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
29d40 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
29d50 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
29d60 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
29d70 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
29d80 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
29d90 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
29da0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
29db0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
29dc0 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
29dd0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
29de0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
29df0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
29e00 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
29e10 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
29e20 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
29e30 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
29e40 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
29e50 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
29e60 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
29e70 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
29e80 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
29e90 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
29ea0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
29eb0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
29ec0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
29ed0 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
29ee0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
29ef0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
29f00 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
29f10 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
29f20 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
29f30 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
29f40 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
29f50 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
29f60 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
29f70 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
29f80 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
29f90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
29fa0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
29fb0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
29fc0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
29fd0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
29fe0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
29ff0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2a000 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2a010 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2a020 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2a030 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2a040 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2a050 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2a060 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2a070 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2a080 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2a090 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2a0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a0b0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2a0c0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2a0d0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2a0e0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2a0f0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2a100 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2a110 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2a120 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2a130 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2a140 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2a150 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2a160 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2a170 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2a180 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2a190 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2a1a0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2a1b0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2a1c0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2a1d0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2a1e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a1f0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2a200 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2a210 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2a220 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2a230 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2a240 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2a250 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2a260 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
2a270 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
2a280 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
2a290 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
2a2a0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
2a2b0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
2a2c0 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
2a2d0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
2a2e0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
2a2f0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
2a300 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
2a310 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
2a320 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
2a330 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2a340 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2a350 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2a360 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2a370 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2a380 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2a390 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2a3a0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2a3b0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2a3c0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2a3d0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2a3e0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2a3f0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2a400 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2a410 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2a420 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2a430 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2a440 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2a450 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2a460 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a470 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2a480 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a490 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2a4a0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2a4b0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2a4c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2a4d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2a4e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2a4f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a500 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2a510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2a520 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2a530 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2a540 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2a550 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2a560 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2a570 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2a580 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2a590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a5a0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2a5b0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2a5c0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2a5d0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2a5e0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2a5f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2a600 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2a610 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2a620 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2a630 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2a640 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2a650 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2a660 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2a670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a680 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2a690 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2a6a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2a6b0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2a6c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2a6d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2a6e0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2a6f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2a700 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2a710 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
2a720 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
2a730 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
2a740 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
2a750 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
2a760 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
2a770 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a780 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2a790 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2a7a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a7b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
2a7c0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
2a7d0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
2a7e0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
2a7f0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
2a800 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
2a810 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
2a820 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2a830 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
2a840 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
2a850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a860 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
2a870 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
2a880 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
2a890 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2a8a0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2a8b0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2a8c0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2a8d0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2a8e0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2a8f0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2a900 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2a910 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2a920 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2a930 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2a940 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2a950 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2a960 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2a970 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2a980 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2a990 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2a9a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
2a9b0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2a9c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a9d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2a9e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2a9f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2aa00 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2aa10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2aa20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2aa30 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2aa40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2aa50 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
2aa60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2aa70 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2aa80 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2aa90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2aaa0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2aab0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2aac0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2aad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2aae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aaf0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2ab00 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2ab10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ab20 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2ab30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2ab40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ab50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ab60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ab70 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2ab80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ab90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2aba0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2abb0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
2abc0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2abd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2abe0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
2abf0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
2ac00 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
2ac10 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2ac20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ac30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
2ac40 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2ac50 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
2ac60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ac70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
2ac80 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2ac90 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
2aca0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
2acb0 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
2acc0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2acd0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
2ace0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
2acf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ad00 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
2ad10 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
2ad20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2ad30 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
2ad40 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
2ad50 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
2ad60 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
2ad70 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
2ad80 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2ad90 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2ada0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
2adb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2adc0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
2add0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
2ade0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
2adf0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
2ae00 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
2ae10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ae20 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
2ae30 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
2ae40 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
2ae50 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2ae60 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
2ae70 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
2ae80 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
2ae90 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
2aea0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
2aeb0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2aec0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
2aed0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
2aee0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
2aef0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
2af00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2af10 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
2af20 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
2af30 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
2af40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
2af50 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
2af60 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
2af70 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
2af80 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
2af90 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
2afa0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
2afb0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
2afc0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
2afd0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
2afe0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
2aff0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2b000 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
2b010 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
2b020 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
2b030 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2b040 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
2b050 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
2b060 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
2b070 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
2b080 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
2b090 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
2b0a0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2b0b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2b0c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b0d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b0e0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2b0f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2b100 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2b110 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2b120 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2b130 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2b140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b150 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2b160 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2b170 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2b180 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2b190 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
2b1a0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2b1b0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2b1c0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2b1d0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2b1e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2b1f0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2b200 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2b210 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2b220 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2b230 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2b240 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2b250 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
2b260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b270 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2b280 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2b290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2b2a0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
2b2b0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2b2c0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
2b2d0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2b2e0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2b2f0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2b300 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2b310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2b320 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2b330 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2b340 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
2b350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b360 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2b370 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2b380 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
2b390 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2b3a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2b3b0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
2b3c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2b3d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b3e0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2b3f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b400 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2b410 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2b420 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
2b430 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2b440 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2b450 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2b460 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2b470 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2b480 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2b490 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2b4a0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
2b4b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2b4c0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2b4d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b4e0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2b4f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2b500 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b520 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2b530 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2b540 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
2b550 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2b560 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2b570 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b580 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b590 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2b5a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b5b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b5c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2b5d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2b5e0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
2b5f0 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
2b600 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2b610 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
2b620 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
2b630 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2b640 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
2b650 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
2b660 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
2b670 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
2b680 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2b690 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
2b6a0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
2b6b0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2b6c0 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
2b6d0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
2b6e0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
2b6f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
2b700 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
2b710 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
2b720 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
2b730 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
2b740 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
2b750 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
2b760 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
2b770 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2b780 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
2b790 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2b7a0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2b7b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
2b7c0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
2b7d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
2b7e0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
2b7f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
2b800 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2b810 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2b820 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
2b830 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2b850 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
2b860 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
2b870 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
2b880 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
2b890 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2b8a0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2b8b0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2b8c0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2b8d0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2b8e0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
2b8f0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2b900 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2b910 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
2b920 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
2b930 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2b940 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2b950 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
2b960 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
2b970 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
2b980 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
2b990 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
2b9a0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
2b9b0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
2b9c0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
2b9d0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
2b9e0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
2b9f0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
2ba00 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
2ba10 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2ba20 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2ba30 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
2ba40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2ba50 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2ba60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2ba70 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2ba80 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
2ba90 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
2baa0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2bab0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2bac0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2bad0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2bae0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
2baf0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
2bb00 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
2bb10 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2bb20 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2bb30 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
2bb40 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
2bb50 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
2bb60 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2bb70 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
2bb80 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
2bb90 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2bba0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2bbb0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2bbc0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2bbd0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2bbe0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2bbf0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2bc00 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2bc10 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2bc20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
2bc30 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2bc40 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
2bc50 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
2bc60 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2bc70 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2bc80 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2bc90 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2bca0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2bcb0 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2bcc0 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2bcd0 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
2bce0 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
2bcf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2bd00 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2bd10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bd20 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2bd30 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2bd40 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2bd50 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2bd60 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2bd70 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
2bd80 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2bd90 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2bda0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2bdb0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2bdc0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2bdd0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2bde0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2bdf0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2be00 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2be10 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2be20 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2be30 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2be40 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2be50 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2be60 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2be70 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2be80 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2be90 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2bea0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
2beb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
2bec0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
2bed0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
2bee0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
2bef0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
2bf00 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
2bf10 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
2bf20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2bf30 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
2bf40 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
2bf50 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
2bf60 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2bf70 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2bf80 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2bf90 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2bfa0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2bfb0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2bfc0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2bfd0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
2bfe0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2bff0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2c000 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2c010 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
2c020 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
2c030 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
2c040 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2c050 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2c060 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2c070 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
2c080 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2c090 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2c0a0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2c0b0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2c0c0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
2c0d0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
2c0e0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
2c0f0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
2c100 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2c110 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
2c120 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
2c130 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2c140 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
2c150 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
2c160 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
2c170 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2c180 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2c190 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
2c1a0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
2c1b0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2c1c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2c1d0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
2c1e0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
2c1f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
2c200 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2c210 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
2c220 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
2c230 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
2c240 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c250 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
2c260 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
2c270 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
2c280 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
2c290 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
2c2a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2c2b0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
2c2c0 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
2c2d0 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
2c2e0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
2c2f0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
2c300 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
2c310 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
2c320 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
2c330 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2c340 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
2c350 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
2c360 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2c370 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2c380 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2c390 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
2c3a0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
2c3b0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
2c3c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2c3d0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
2c3e0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
2c3f0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
2c400 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
2c410 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
2c420 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
2c430 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
2c440 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2c450 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
2c460 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2c470 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
2c480 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
2c490 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
2c4a0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
2c4b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
2c4c0 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
2c4d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c4e0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
2c4f0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
2c500 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
2c510 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2c520 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2c530 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
2c540 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
2c550 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2c560 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
2c570 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
2c580 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
2c590 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2c5a0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
2c5b0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2c5c0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2c5d0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2c5e0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
2c5f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2c600 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
2c610 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
2c620 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
2c630 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
2c640 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2c650 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2c660 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2c670 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
2c680 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
2c690 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
2c6a0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
2c6b0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
2c6c0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
2c6d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2c6e0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
2c6f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c700 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2c710 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
2c720 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
2c730 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
2c740 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
2c750 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
2c760 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
2c770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
2c780 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
2c790 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2c7a0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
2c7b0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
2c7c0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2c7d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2c7e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
2c7f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2c800 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2c810 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2c820 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2c830 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2c840 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2c850 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2c860 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c870 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c880 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2c890 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2c8a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2c8b0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2c8c0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2c8d0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2c8e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c8f0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2c900 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2c910 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2c920 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2c930 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2c940 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2c950 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2c960 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c970 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c980 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c990 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2c9a0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c9b0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c9c0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2c9d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2c9e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2c9f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2ca00 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2ca10 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2ca20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2ca30 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2ca40 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2ca50 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2ca60 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2ca70 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2ca80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2ca90 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2caa0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2cab0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2cac0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2cad0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2cae0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
2caf0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2cb00 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2cb10 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2cb20 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
2cb30 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2cb40 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2cb50 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2cb60 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2cb70 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2cb80 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2cb90 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2cba0 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2cbb0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2cbc0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2cbd0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2cbe0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2cbf0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2cc00 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2cc10 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2cc20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2cc30 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2cc40 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2cc50 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2cc60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2cc70 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2cc80 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2cc90 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2cca0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ccb0 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2ccc0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2ccd0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
2cce0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
2ccf0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
2cd00 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2cd10 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
2cd20 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2cd30 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2cd40 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2cd50 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2cd60 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2cd70 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
2cd80 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
2cd90 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
2cda0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2cdb0 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
2cdc0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2cdd0 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
2cde0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
2cdf0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
2ce00 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2ce10 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
2ce20 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
2ce30 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
2ce40 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
2ce50 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
2ce60 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2ce70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
2ce80 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2ce90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2cea0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2ceb0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
2cec0 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2ced0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2cee0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2cef0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2cf00 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2cf10 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2cf20 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2cf30 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2cf40 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
2cf50 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
2cf60 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
2cf70 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
2cf80 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
2cf90 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2cfa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
2cfb0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
2cfc0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
2cfd0 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
2cfe0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2cff0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2d000 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
2d010 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
2d020 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
2d030 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
2d040 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
2d050 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
2d060 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2d070 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
2d080 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
2d090 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
2d0a0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2d0b0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2d0c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2d0d0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2d0e0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2d0f0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2d100 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2d110 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2d120 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2d130 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d140 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2d150 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d160 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2d170 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2d180 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2d190 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2d1a0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2d1b0 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
2d1c0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2d1d0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2d1e0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2d1f0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2d200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d210 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2d220 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2d230 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2d240 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2d250 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2d260 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2d270 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2d280 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2d290 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2d2a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2d2b0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2d2c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2d2d0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2d2e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d2f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2d300 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2d310 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2d320 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2d330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d340 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2d350 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2d360 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2d370 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2d380 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2d390 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2d3a0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2d3b0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2d3c0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2d3d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2d3e0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2d3f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d400 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2d410 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2d420 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2d430 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2d440 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2d450 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2d460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d470 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
2d480 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
2d490 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2d4a0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
2d4b0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
2d4c0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
2d4d0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2d4e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d4f0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2d500 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2d510 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2d520 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2d530 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2d540 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2d550 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2d560 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
2d570 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2d580 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
2d590 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2d5a0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
2d5b0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
2d5c0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
2d5d0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
2d5e0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
2d5f0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
2d600 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
2d610 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
2d620 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
2d630 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
2d640 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
2d650 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
2d660 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
2d670 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
2d680 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2d690 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2d6a0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2d6b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2d6c0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
2d6d0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
2d6e0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2d6f0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
2d700 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2d710 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
2d720 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
2d730 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
2d740 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2d750 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2d760 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2d770 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
2d780 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
2d790 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2d7a0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
2d7b0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
2d7c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2d7d0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
2d7e0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
2d7f0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
2d800 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d810 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2d820 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2d830 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
2d840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d850 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2d860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d870 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
2d880 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2d890 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2d8a0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2d8b0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2d8c0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2d8d0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2d8e0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2d8f0 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
2d900 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2d910 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2d920 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2d930 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d940 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d950 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2d960 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2d970 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2d980 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2d990 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2d9a0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2d9b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2d9c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d9d0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2d9e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d9f0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2da00 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2da10 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2da20 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2da30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2da40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2da50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2da60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2da70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2da80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2da90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2daa0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2dab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2dac0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2dad0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2dae0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2daf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2db00 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2db10 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2db20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2db30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2db40 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2db50 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2db60 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
2db70 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
2db80 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2db90 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
2dba0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2dbb0 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
2dbc0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
2dbd0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2dbe0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
2dbf0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2dc00 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
2dc10 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
2dc20 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
2dc30 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
2dc40 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
2dc50 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
2dc60 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
2dc70 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
2dc80 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2dc90 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2dca0 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
2dcb0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2dcc0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
2dcd0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2dce0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
2dcf0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
2dd00 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
2dd10 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
2dd20 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
2dd30 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
2dd40 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2dd50 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
2dd60 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
2dd70 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
2dd80 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
2dd90 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
2dda0 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
2ddb0 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
2ddc0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
2ddd0 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
2dde0 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
2ddf0 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
2de00 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
2de10 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
2de20 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2de30 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
2de40 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
2de50 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
2de60 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
2de70 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
2de80 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
2de90 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2dea0 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
2deb0 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
2dec0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
2ded0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
2dee0 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
2def0 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
2df00 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2df10 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
2df20 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
2df30 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
2df40 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
2df50 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
2df60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
2df70 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
2df80 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
2df90 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
2dfa0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
2dfb0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2dfc0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
2dfd0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
2dfe0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
2dff0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
2e000 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
2e010 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
2e020 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
2e030 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
2e040 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e050 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
2e060 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2e070 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
2e080 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
2e090 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2e0a0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
2e0b0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
2e0c0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2e0d0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2e0e0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
2e0f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2e100 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
2e110 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
2e120 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2e130 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2e140 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
2e150 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
2e160 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
2e170 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
2e180 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
2e190 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2e1a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
2e1b0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
2e1c0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
2e1d0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2e1e0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
2e1f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2e200 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2e210 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2e220 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2e230 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2e240 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2e250 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2e260 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2e270 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2e280 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
2e290 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
2e2a0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
2e2b0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
2e2c0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
2e2d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e2e0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2e2f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2e300 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2e310 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2e320 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2e330 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2e340 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2e350 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2e360 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2e370 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2e380 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e390 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2e3a0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2e3b0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2e3c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2e3d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2e3e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2e3f0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2e400 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2e410 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e420 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2e430 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2e440 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2e450 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2e460 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
2e470 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2e480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e490 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2e4a0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
2e4b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2e4c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2e4d0 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2e4e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2e4f0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2e500 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2e510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e520 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2e530 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2e540 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e550 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2e560 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2e570 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2e580 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2e590 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2e5a0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2e5b0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2e5c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
2e5d0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
2e5e0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
2e5f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2e600 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e610 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
2e620 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
2e630 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2e640 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2e650 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2e660 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2e670 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2e680 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
2e690 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
2e6a0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
2e6b0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
2e6c0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
2e6d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2e6e0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
2e6f0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
2e700 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
2e710 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
2e720 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
2e730 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
2e740 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
2e750 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
2e760 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
2e770 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
2e780 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
2e790 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
2e7a0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
2e7b0 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
2e7c0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2e7d0 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
2e7e0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
2e7f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2e800 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2e810 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2e820 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2e830 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2e840 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2e850 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2e860 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2e870 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2e880 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2e890 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2e8a0 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2e8b0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2e8c0 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2e8d0 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2e8e0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2e8f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
2e900 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e910 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e920 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e930 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
2e940 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
2e950 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
2e960 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
2e970 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
2e980 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
2e990 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
2e9a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e9b0 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
2e9c0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
2e9d0 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
2e9e0 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
2e9f0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2ea00 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
2ea10 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2ea20 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
2ea30 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
2ea40 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
2ea50 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
2ea60 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
2ea70 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
2ea80 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2ea90 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2eaa0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2eab0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2eac0 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
2ead0 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
2eae0 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
2eaf0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
2eb00 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
2eb10 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
2eb20 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2eb30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2eb40 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
2eb50 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
2eb60 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2eb70 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
2eb80 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
2eb90 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
2eba0 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
2ebb0 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
2ebc0 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2ebd0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2ebe0 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2ebf0 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2ec00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2ec10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2ec20 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2ec30 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2ec40 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2ec50 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2ec60 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2ec70 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2ec80 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2ec90 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2eca0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2ecb0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2ecc0 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2ecd0 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2ece0 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2ecf0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2ed00 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2ed10 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
2ed20 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
2ed30 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
2ed40 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
2ed50 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
2ed60 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
2ed70 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
2ed80 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
2ed90 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2eda0 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2edb0 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2edc0 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2edd0 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2ede0 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2edf0 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2ee00 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2ee10 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
2ee20 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
2ee30 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2ee40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2ee50 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2ee60 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
2ee70 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2ee80 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2ee90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2eea0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2eeb0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
2eec0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2eed0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2eee0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
2eef0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
2ef00 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
2ef10 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
2ef20 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
2ef30 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
2ef40 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
2ef50 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
2ef60 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
2ef70 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
2ef80 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
2ef90 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
2efa0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
2efb0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
2efc0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
2efd0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
2efe0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
2eff0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
2f000 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
2f010 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
2f020 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
2f030 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
2f040 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
2f050 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2f060 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
2f070 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
2f080 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
2f090 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2f0a0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
2f0b0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
2f0c0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
2f0d0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
2f0e0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
2f0f0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
2f100 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
2f110 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
2f120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
2f130 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
2f140 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
2f150 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
2f160 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
2f170 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
2f180 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
2f190 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
2f1a0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2f1b0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
2f1c0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
2f1d0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
2f1e0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2f1f0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
2f200 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
2f210 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2f220 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
2f230 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
2f240 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
2f250 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
2f260 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
2f270 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2f280 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
2f290 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2f2a0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
2f2b0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
2f2c0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2f2d0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
2f2e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f2f0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2f300 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f310 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
2f320 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2f330 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2f340 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
2f350 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
2f360 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
2f370 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
2f380 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
2f390 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
2f3a0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
2f3b0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
2f3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
2f3d0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
2f3e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
2f3f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2f400 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2f410 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
2f420 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f430 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
2f440 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2f450 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2f460 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f470 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f480 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
2f490 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
2f4a0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
2f4b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2f4c0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
2f4d0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
2f4e0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
2f4f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
2f500 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f510 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2f520 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
2f530 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
2f540 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2f550 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f560 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
2f570 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
2f580 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
2f590 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
2f5a0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
2f5b0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f5c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
2f5d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f5e0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
2f5f0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f600 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2f610 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2f620 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f630 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
2f640 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2f650 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
2f660 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
2f670 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2f680 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f690 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2f6a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f6b0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
2f6c0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
2f6d0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
2f6e0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
2f6f0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
2f700 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2f710 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2f720 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2f730 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2f740 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2f750 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2f760 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2f770 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2f780 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2f790 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
2f7a0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
2f7b0 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
2f7c0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2f7d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
2f7e0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
2f7f0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
2f800 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2f810 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f820 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
2f830 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
2f840 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
2f850 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2f860 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2f870 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2f880 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f890 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2f8a0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2f8b0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2f8c0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2f8d0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2f8e0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2f8f0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2f900 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2f910 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2f920 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f930 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
2f940 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f950 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
2f960 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2f970 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
2f980 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
2f990 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
2f9a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2f9b0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
2f9c0 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
2f9d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f9e0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2f9f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2fa00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
2fa10 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
2fa20 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
2fa30 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
2fa40 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
2fa50 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
2fa60 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
2fa70 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
2fa80 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
2fa90 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
2faa0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
2fab0 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
2fac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fad0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
2fae0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
2faf0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
2fb00 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
2fb10 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
2fb20 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
2fb30 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
2fb40 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
2fb50 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
2fb60 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
2fb70 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2fb80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fb90 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2fba0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2fbb0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2fbc0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2fbd0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2fbe0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2fbf0 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
2fc00 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2fc10 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2fc20 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
2fc30 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
2fc40 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
2fc50 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
2fc60 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
2fc70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fc80 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
2fc90 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
2fca0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
2fcb0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
2fcc0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
2fcd0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
2fce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fcf0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2fd00 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2fd10 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2fd20 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2fd30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fd40 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2fd50 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2fd60 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2fd70 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2fd80 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
2fd90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2fda0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
2fdb0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2fdc0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2fdd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fde0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2fdf0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
2fe00 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2fe10 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2fe20 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2fe30 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2fe40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fe50 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
2fe60 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2fe70 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2fe80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2fe90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2fea0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2feb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2fec0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
2fed0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2fee0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
2fef0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2ff00 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
2ff10 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
2ff20 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
2ff30 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
2ff40 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
2ff50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ff60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
2ff70 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
2ff80 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
2ff90 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
2ffa0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2ffb0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
2ffc0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
2ffd0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
2ffe0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
2fff0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
30000 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
30010 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
30020 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
30030 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
30040 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
30050 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30060 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
30070 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
30080 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
30090 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
300a0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
300b0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
300c0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
300d0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
300e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
300f0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
30100 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
30110 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
30120 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
30130 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
30140 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
30150 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
30160 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
30170 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
30180 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
30190 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
301a0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
301b0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
301c0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
301d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
301e0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
301f0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33  esult.  If the 3
30200 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
30210 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
30220 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65  en it.** must be
30230 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
30240 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67   into the string
30250 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
30260 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a  erminator would.
30270 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65  ** appear if the
30280 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55   string where NU
30290 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  L terminated.  I
302a0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
302b0 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ters occur.** in
302c0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61   the string at a
302d0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61   byte offset tha
302e0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  t is less than t
302f0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
30300 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  3rd.** parameter
30310 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
30320 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c  ting string will
30330 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
30340 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a  d NULs and the.*
30350 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  * result of expr
30360 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e  essions operatin
30370 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74  g on strings wit
30380 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
30390 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
303a0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
303b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
303c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
303d0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
303e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
303f0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
30400 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
30410 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
30420 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
30430 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
30440 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
30450 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
30460 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
30470 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
30480 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
30490 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
304a0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
304b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
304c0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
304d0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
304e0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
304f0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
30500 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
30510 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
30520 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
30530 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
30540 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
30550 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
30560 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
30570 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
30580 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
30590 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
305a0 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
305b0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
305c0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
305d0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
305e0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
305f0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
30600 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
30610 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
30620 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30630 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
30640 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
30650 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
30660 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
30670 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
30680 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
30690 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
306a0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
306b0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
306c0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
306d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
306e0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
306f0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30700 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
30710 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30720 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30730 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
30740 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
30750 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30760 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
30770 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
30780 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
30790 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
307a0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
307b0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
307c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
307d0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
307e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
307f0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
30800 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
30810 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
30820 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
30830 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
30840 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
30850 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
30860 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
30870 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30880 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
30890 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
308a0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
308b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
308c0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
308d0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
308e0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
308f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30900 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
30910 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
30920 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
30930 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30940 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
30950 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
30960 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
30970 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
30980 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
30990 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
309a0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
309b0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
309c0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
309d0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
309e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
309f0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
30a00 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
30a10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
30a20 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
30a30 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
30a40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
30a50 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
30a60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
30a70 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
30a80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30a90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30aa0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
30ab0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
30ac0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
30ad0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
30ae0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
30af0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
30b00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30b10 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
30b20 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
30b30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30b40 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
30b50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
30b60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30b70 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
30b80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30b90 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
30ba0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
30bb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30bc0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
30bd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
30be0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30bf0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
30c00 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
30c10 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
30c20 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
30c30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30c40 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
30c50 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
30c60 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
30c70 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
30c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30c90 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
30ca0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
30cb0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
30cc0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
30cd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30ce0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
30cf0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30d00 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
30d10 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
30d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30d30 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
30d40 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
30d50 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
30d60 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
30d70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30d80 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
30d90 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
30da0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
30db0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
30dc0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
30dd0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
30de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30df0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
30e00 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
30e10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
30e20 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
30e30 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
30e40 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
30e50 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
30e60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
30e70 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
30e80 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
30e90 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30ea0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
30eb0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
30ec0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
30ed0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
30ee0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
30ef0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
30f00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
30f10 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
30f20 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
30f30 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
30f40 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
30f50 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
30f60 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
30f70 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
30f80 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
30f90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
30fa0 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
30fb0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
30fc0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
30fd0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
30fe0 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
30ff0 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
31000 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
31010 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
31020 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
31030 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
31040 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
31050 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
31060 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
31070 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
31080 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
31090 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
310a0 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
310b0 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
310c0 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
310d0 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
310e0 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
310f0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
31100 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
31110 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
31120 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
31130 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
31140 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
31150 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
31160 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
31170 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
31180 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
31190 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
311a0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
311b0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
311c0 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
311d0 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
311e0 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
311f0 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
31200 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
31210 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
31220 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
31230 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
31240 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
31250 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
31260 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
31270 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
31280 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
31290 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
312a0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
312b0 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
312c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
312d0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
312e0 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
312f0 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
31300 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
31310 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
31320 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
31330 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
31340 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
31350 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
31360 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
31370 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
31380 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
31390 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
313a0 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
313b0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
313c0 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
313d0 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
313e0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
313f0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
31400 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
31410 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31420 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
31430 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
31440 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
31450 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
31460 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
31470 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
31480 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
31490 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
314a0 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
314b0 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
314c0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
314d0 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
314e0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
314f0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
31500 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
31510 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
31520 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
31530 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
31540 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
31550 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
31560 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
31570 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
31580 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
31590 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
315a0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
315b0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
315c0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
315d0 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
315e0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
315f0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
31600 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69  ame answer.** gi
31610 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70  ven the same inp
31620 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20  uts.  If two or 
31630 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  more collating f
31640 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67  unctions are reg
31650 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68  istered.** to th
31660 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e  e same collation
31670 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66   name (using dif
31680 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
31690 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c  values) then all
316a0 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e  .** must give an
316b0 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77   equivalent answ
316c0 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20  er when invoked 
316d0 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20  with equivalent 
316e0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  strings..** The 
316f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31700 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65  on must obey the
31710 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65   following prope
31720 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a  rties for all.**
31730 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61   strings A, B, a
31740 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  nd C:.**.** <ol>
31750 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
31760 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c   then B==A..** <
31770 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20  li> If A==B and 
31780 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a  B==C then A==C..
31790 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
317a0 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a  B THEN B&gt;A..*
317b0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
317c0 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e   and B&lt;C then
317d0 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c   A&lt;C..** </ol
317e0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c  >.**.** If a col
317f0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
31800 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65  fails any of the
31810 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e   above constrain
31820 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63  ts and that.** c
31830 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
31840 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64  n is  registered
31850 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20   and used, then 
31860 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
31870 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64  SQLite.** is und
31880 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
31890 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
318a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
318b0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
318c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
318d0 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74  tion().** with t
318e0 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  he addition that
318f0 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61   the xDestroy ca
31900 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
31910 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a  d on pArg when.*
31920 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * the collating 
31930 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
31940 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  ted..** ^Collati
31950 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
31960 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
31970 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
31980 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61  n by later.** ca
31990 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
319a0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
319b0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
319c0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
319d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
319e0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
319f0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
31a00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74  **.** ^The xDest
31a10 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
31a20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65  <u>not</u> calle
31a30 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c  d if the .** sql
31a40 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31a50 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74  ation_v2() funct
31a60 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c  ion fails.  Appl
31a70 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e  ications that in
31a80 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
31a90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31aa0 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e  _v2() with a non
31ab0 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61  -NULL xDestroy a
31ac0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a  rgument should .
31ad0 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ** check the ret
31ae0 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73  urn code and dis
31af0 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c  pose of the appl
31b00 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
31b10 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76  nter.** themselv
31b20 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65  es rather than e
31b30 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20  xpecting SQLite 
31b40 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20  to deal with it 
31b50 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69  for them..** Thi
31b60 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66  s is different f
31b70 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20  rom every other 
31b80 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
31b90 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74  .  The inconsist
31ba0 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f  ency .** is unfo
31bb0 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e  rtunate but cann
31bc0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69  ot be changed wi
31bd0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62  thout breaking b
31be0 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d  ackwards .** com
31bf0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
31c00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
31c10 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31c20 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
31c30 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
31c40 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
31c50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
31c60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
31c70 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
31c80 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
31c90 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
31ca0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
31cb0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
31cc0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
31cd0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
31ce0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
31cf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31d00 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
31d10 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
31d20 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
31d30 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
31d40 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
31d50 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
31d60 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
31d70 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
31d80 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
31d90 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
31da0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
31db0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31dc0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
31dd0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
31de0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
31df0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
31e00 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
31e10 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
31e20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
31e30 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
31e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31e50 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
31e60 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
31e70 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
31e80 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
31e90 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
31ea0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
31eb0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
31ec0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
31ed0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
31ee0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
31ef0 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
31f00 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
31f10 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
31f20 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
31f30 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
31f40 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
31f50 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
31f60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e  *.** ^If the fun
31f70 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
31f80 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
31f90 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31fa0 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
31fb0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
31fc0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
31fd0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
31fe0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
31ff0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
32000 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49  ded in UTF-8. ^I
32010 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
32020 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
32030 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
32040 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
32050 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
32060 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
32070 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61   order..** ^A ca
32080 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
32090 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
320a0 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c  he existing coll
320b0 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c  ation-needed cal
320c0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57  lback..**.** ^(W
320d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
320e0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
320f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
32100 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
32110 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
32120 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
32130 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
32140 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
32150 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
32160 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
32170 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
32180 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
32190 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
321a0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
321b0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
321c0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
321d0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
321e0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
321f0 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
32200 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
32210 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
32220 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
32230 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
32240 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
32250 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32260 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
32270 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
32280 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32290 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ce.)^.**.** The 
322a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
322b0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
322c0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
322d0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
322e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
322f0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
32300 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32310 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
32320 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
32330 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
32340 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
32350 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32360 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
32370 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
32380 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
32390 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
323a0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
323b0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
323c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
323d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
323e0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
323f0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
32400 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
32410 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
32420 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48  .#ifdef SQLITE_H
32430 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
32440 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
32450 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
32460 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
32470 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
32480 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
32490 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
324a0 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
324b0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
324c0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
324d0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
324e0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
324f0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
32500 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32510 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
32520 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
32530 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
32540 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
32550 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
32560 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
32570 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
32580 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
32590 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
325a0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
325b0 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
325c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
325d0 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
325e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
325f0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
32600 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
32610 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
32620 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
32630 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
32640 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
32650 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
32660 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
32670 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
32680 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
32690 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
326a0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
326b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
326c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
326d0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
326e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
326f0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
32700 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
32710 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
32720 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
32730 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
32740 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
32750 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
32760 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
32770 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
32780 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
32790 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
327a0 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
327b0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
327c0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
327d0 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
327e0 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
327f0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
32800 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
32810 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
32820 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
32830 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
32840 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
32850 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
32860 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
32870 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
32880 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
32890 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
328a0 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
328b0 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
328c0 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
328d0 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
328e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
328f0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
32900 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
32910 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
32920 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
32930 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
32940 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
32950 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
32960 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
32970 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
32980 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
32990 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
329a0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
329b0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
329c0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
329d0 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
329e0 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
329f0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
32a00 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
32a10 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
32a20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
32a30 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
32a40 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
32a50 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
32a60 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
32a70 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
32a80 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
32a90 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
32aa0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  rned..**.** ^SQL
32ab0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
32ac0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
32ad0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
32ae0 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
32af0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
32b00 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
32b10 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c  ect.  If the xSl
32b20 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20  eep() method.** 
32b30 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  of the default V
32b40 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  FS is not implem
32b50 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c  ented correctly,
32b60 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   or not implemen
32b70 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74  ted at.** all, t
32b80 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32b90 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65   of sqlite3_slee
32ba0 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20  p() may deviate 
32bb0 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70  from the descrip
32bc0 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70  tion.** in the p
32bd0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
32be0 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  hs..*/.int sqlit
32bf0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
32c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32c10 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
32c20 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
32c30 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
32c40 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
32c50 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
32c60 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
32c70 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
32c80 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
32c90 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
32ca0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
32cb0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
32cc0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
32cd0 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
32ce0 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
32cf0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
32d00 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
32d10 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
32d20 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
32d30 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
32d40 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
32d50 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
32d60 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
32d70 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
32d80 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
32d90 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
32da0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
32db0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
32dc0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
32dd0 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
32de0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
32df0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
32e00 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
32e10 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
32e20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
32e30 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
32e40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
32e50 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
32e60 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
32e70 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
32e80 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
32e90 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
32ea0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
32eb0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
32ec0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
32ed0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
32ee0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
32ef0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
32f00 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
32f10 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
32f20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
32f30 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
32f40 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
32f50 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
32f60 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
32f70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
32f80 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
32f90 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
32fa0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
32fb0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
32fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
32fd0 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
32fe0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
32ff0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
33000 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
33010 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
33020 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
33030 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
33040 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
33050 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
33060 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
33070 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
33080 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
33090 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
330a0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
330b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
330c0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
330d0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
330e0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
330f0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
33100 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
33110 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
33120 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
33130 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
33140 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
33150 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
33160 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
33170 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
33180 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
33190 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
331a0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
331b0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
331c0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
331d0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
331e0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
331f0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
33200 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
33210 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
33220 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
33230 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
33240 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
33250 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
33260 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
33270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33280 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
33290 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
332a0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
332b0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
332c0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
332d0 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
332e0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
332f0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
33300 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
33310 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
33320 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
33330 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
33340 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
33350 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
33360 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
33370 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
33380 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
33390 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
333a0 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
333b0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
333c0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
333d0 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
333e0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
333f0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
33400 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
33410 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
33420 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
33430 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
33440 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
33450 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
33460 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
33470 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
33480 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
33490 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
334a0 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
334b0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
334c0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
334d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
334e0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
334f0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
33500 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
33510 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
33520 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
33530 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
33540 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
33550 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
33560 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
33570 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
33580 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
33590 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
335a0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
335b0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
335c0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
335d0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
335e0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
335f0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
33600 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
33610 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
33620 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
33630 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
33640 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
33650 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
33660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
33670 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
33680 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
33690 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
336a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
336b0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
336c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
336d0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
336e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
336f0 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
33700 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
33710 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
33720 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
33730 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
33740 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
33750 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
33760 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
33770 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33780 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
33790 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
337a0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
337b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
337c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
337d0 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
337e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
337f0 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
33800 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
33810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33820 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
33830 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
33840 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
33850 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33860 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
33870 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
33880 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
33890 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
338a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
338b0 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
338c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
338d0 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
338e0 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
338f0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
33900 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
33910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
33920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33930 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
33940 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33950 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
33960 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
33970 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
33980 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
33990 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
339a0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
339b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
339c0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
339d0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
339e0 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
339f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33a00 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33a10 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
33a20 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
33a30 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
33a40 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
33a50 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
33a60 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
33a70 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
33a80 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
33a90 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
33aa0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
33ab0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
33ac0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
33ad0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
33ae0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
33af0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
33b00 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
33b10 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
33b20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33b30 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
33b40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33b50 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
33b60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
33b70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
33b80 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
33b90 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
33ba0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
33bb0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
33bc0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
33bd0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
33be0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
33bf0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
33c00 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
33c10 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
33c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33c30 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
33c40 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
33c50 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
33c60 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
33c70 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
33c80 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
33c90 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
33ca0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
33cb0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
33cc0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
33cd0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
33ce0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
33cf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33d00 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
33d10 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
33d20 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
33d30 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
33d40 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
33d50 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
33d60 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
33d70 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
33d80 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
33d90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33da0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
33db0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
33dc0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
33dd0 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
33de0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69  .**.** The commi
33df0 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68  t and rollback h
33e00 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ook callbacks ar
33e10 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  e not reentrant.
33e20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
33e30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33e40 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
33e50 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
33e60 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
33e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33e80 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
33e90 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
33ea0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
33eb0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
33ec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
33ed0 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
33ee0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
33ef0 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
33f00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
33f10 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
33f20 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
33f30 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
33f40 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
33f50 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
33f60 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67  ote that running
33f70 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73   any other SQL s
33f80 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75  tatements, inclu
33f90 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74  ding SELECT stat
33fa0 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65  ements,.** or me
33fb0 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  rely calling [sq
33fc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33fd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33fe0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f  _step()] will mo
33ff0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
34000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
34010 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
34020 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
34030 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
34040 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
34050 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
34060 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
34070 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
34080 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
34090 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
340a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
340b0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
340c0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
340d0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
340e0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
340f0 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
34100 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
34110 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
34120 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
34130 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
34140 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
34150 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
34160 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
34170 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
34180 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
34190 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
341a0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
341b0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
341c0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
341d0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
341e0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
341f0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
34200 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
34210 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
34220 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
34230 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
34240 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
34250 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
34260 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
34270 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
34280 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
34290 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
342a0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
342b0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
342c0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
342d0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
342e0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
342f0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
34300 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
34310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34320 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
34330 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
34340 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
34350 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
34360 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
34370 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
34380 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
34390 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
343a0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
343b0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
343c0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
343d0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
343e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
343f0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
34400 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
34410 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
34420 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
34430 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
34440 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
34450 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
34460 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
34470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34480 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
34490 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
344a0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
344b0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
344c0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
344d0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
344e0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
344f0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
34500 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
34510 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
34520 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
34530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34540 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
34550 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
34560 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
34570 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
34580 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
34590 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
345a0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
345b0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
345c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
345d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
345e0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
345f0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
34600 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
34610 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
34620 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
34630 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
34640 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
34650 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
34660 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
34670 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
34680 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
34690 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
346a0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
346b0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
346c0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
346d0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
346e0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
346f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
34700 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
34710 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
34720 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
34730 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
34740 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
34750 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
34760 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
34770 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
34780 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
34790 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
347a0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
347b0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
347c0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
347d0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
347e0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
347f0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
34800 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
34810 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
34820 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
34830 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
34840 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
34850 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
34860 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
34870 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
34880 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
34890 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
348a0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
348b0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
348c0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
348d0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
348e0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
348f0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
34900 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
34910 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
34920 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
34930 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
34940 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
34950 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
34960 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
34970 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
34980 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
34990 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
349a0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
349b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
349c0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
349d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
349e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
349f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
34a00 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
34a10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34a20 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
34a30 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
34a40 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
34a50 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
34a60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34a70 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
34a80 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
34a90 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
34aa0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34ab0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
34ac0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
34ad0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
34ae0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
34af0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
34b00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
34b10 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
34b20 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
34b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
34b40 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
34b50 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
34b60 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
34b70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34b80 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
34b90 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
34ba0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
34bb0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
34bc0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
34bd0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
34be0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34bf0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
34c00 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
34c10 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
34c20 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
34c30 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
34c40 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
34c50 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
34c60 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
34c70 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
34c80 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
34c90 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34ca0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
34cb0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
34cc0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
34cd0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
34ce0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
34cf0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
34d00 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
34d10 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
34d20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
34d30 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
34d40 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
34d50 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
34d60 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
34d70 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
34d80 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
34d90 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
34da0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
34db0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34dc0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
34dd0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
34de0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
34df0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
34e00 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
34e10 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
34e20 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
34e30 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
34e40 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
34e50 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
34e60 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
34e70 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
34e80 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
34e90 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
34ea0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
34eb0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
34ec0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
34ed0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
34ee0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
34ef0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
34f00 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
34f10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
34f20 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
34f30 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
34f40 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
34f50 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
34f60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
34f70 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
34f80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
34f90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
34fa0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
34fb0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
34fc0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
34fd0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
34fe0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
34ff0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
35000 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
35010 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
35020 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
35030 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
35040 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
35050 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
35060 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
35070 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
35080 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
35090 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
350a0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
350b0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
350c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
350d0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
350e0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
350f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
35100 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
35110 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
35120 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
35130 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
35140 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
35150 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
35160 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
35170 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
35180 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
35190 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
351a0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
351b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
351c0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
351d0 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
351e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
351f0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
35200 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
35210 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
35220 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
35230 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
35240 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
35250 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
35260 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
35270 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
35280 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
35290 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
352a0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
352b0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
352c0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
352d0 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
352e0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
352f0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
35300 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
35310 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35320 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
35330 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
35340 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
35350 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
35360 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
35370 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35380 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
35390 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
353a0 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
353b0 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
353c0 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
353d0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
353e0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
353f0 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74  AGEMENT]..*/.int
35400 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
35410 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
35420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
35430 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
35440 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
35450 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
35460 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
35470 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35480 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
35490 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
354a0 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
354b0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
354c0 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
354d0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
354e0 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
354f0 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
35500 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
35510 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
35520 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
35530 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
35540 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
35550 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
35560 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
35570 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
35580 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
35590 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
355a0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
355b0 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
355c0 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
355d0 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
355e0 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
355f0 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
35600 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
35610 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
35620 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
35630 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
35640 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
35650 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
35660 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
35670 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
35680 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
35690 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
356a0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
356b0 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
356c0 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
356d0 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
356e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
356f0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
35700 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
35710 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
35720 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
35730 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
35740 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
35750 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
35760 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
35770 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
35780 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
35790 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
357a0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
357b0 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
357c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
357d0 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
357e0 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
357f0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
35800 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
35810 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
35820 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
35830 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
35840 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
35850 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
35860 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
35870 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
35880 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
35890 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
358a0 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
358b0 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
358c0 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
358d0 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
358e0 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
358f0 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
35900 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
35910 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
35920 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
35930 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
35940 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
35950 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
35960 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
35970 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
35980 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
35990 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
359a0 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
359b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
359c0 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75  n is specified u
359d0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
359e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
359f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
35a00 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c  CHE2],...)..** <
35a10 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63  li> The page cac
35a20 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f  he allocates fro
35a30 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79  m its own memory
35a40 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a   pool supplied.*
35a50 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74  *      by [sqlit
35a60 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
35a70 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
35a80 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72  CHE],...) rather
35a90 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72   than.**      fr
35aa0 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20  om the heap..** 
35ab0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65  </ul>)^.**.** Be
35ac0 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
35ad0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
35ae0 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  3, the soft heap
35af0 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
35b00 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ed.** regardless
35b10 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
35b20 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  ot the [SQLITE_E
35b30 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
35b40 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70  AGEMENT].** comp
35b50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
35b60 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74  is invoked.  Wit
35b70 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
35b80 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
35b90 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74  NT],.** the soft
35ba0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
35bb0 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79  nforced on every
35bc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
35bd0 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20  on.  Without.** 
35be0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
35bf0 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
35c00 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ], the soft heap
35c10 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65   limit is only e
35c20 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20  nforced.** when 
35c30 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
35c40 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ted by the page 
35c50 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20  cache.  Testing 
35c60 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65  suggests that be
35c70 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67  cause.** the pag
35c80 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70  e cache is the p
35c90 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72  redominate memor
35ca0 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65  y user in SQLite
35cb0 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  , most.** applic
35cc0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69  ations will achi
35cd0 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66  eve adequate sof
35ce0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66  t heap limit enf
35cf0 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74  orcement without
35d00 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b  .** the use of [
35d10 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
35d20 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
35d30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63  ..**.** The circ
35d40 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20  umstances under 
35d50 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c  which SQLite wil
35d60 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f  l enforce the so
35d70 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61  ft heap limit ma
35d80 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  y.** changes in 
35d90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
35da0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71  of SQLite..*/.sq
35db0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
35dc0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
35dd0 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e  mit64(sqlite3_in
35de0 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t64 N);../*.** C
35df0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
35e00 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69  ted Soft Heap Li
35e10 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  mit Interface.**
35e20 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
35e30 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72  * This is a depr
35e40 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f  ecated version o
35e50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
35e60 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
35e70 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
35e80 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
35e90 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
35ea0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
35eb0 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79  tibility.** only
35ec0 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69  .  All new appli
35ed0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75  cations should u
35ee0 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
35ef0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
35f00 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63  it64()] interfac
35f10 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68  e rather than th
35f20 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54  is one..*/.SQLIT
35f30 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
35f40 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
35f50 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29  eap_limit(int N)
35f60 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
35f70 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
35f80 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
35f90 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
35fa0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
35fb0 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
35fc0 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
35fd0 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
35fe0 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
35ff0 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
36000 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
36010 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36020 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
36030 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
36040 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
36050 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36060 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
36070 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
36080 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
36090 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
360a0 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
360b0 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
360c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
360d0 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
360e0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
360f0 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
36100 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
36110 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
36120 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
36130 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
36140 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
36150 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
36160 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
36170 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
36180 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
36190 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
361a0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
361b0 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
361c0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
361d0 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
361e0 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
361f0 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
36200 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
36210 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
36220 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
36230 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
36240 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
36250 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
36260 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
36270 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
36280 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
36290 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
362a0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
362b0 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
362c0 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
362d0 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
362e0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
362f0 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
36300 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
36310 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
36320 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
36330 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
36340 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
36350 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
36360 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
36370 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
36380 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
36390 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
363a0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
363b0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
363c0 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
363d0 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
363e0 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
363f0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
36400 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
36410 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
36420 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
36430 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
36440 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
36450 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
36460 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
36470 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
36480 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
36490 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
364a0 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
364b0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
364c0 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
364d0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
364e0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
364f0 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
36500 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
36510 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
36520 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
36530 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
36540 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
36550 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
36560 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
36570 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
36580 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
36590 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
365a0 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
365b0 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
365c0 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
365d0 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
365e0 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
365f0 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
36600 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
36610 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
36620 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
36630 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
36640 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
36650 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
36660 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
36670 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
36680 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
36690 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
366a0 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
366b0 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
366c0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
366d0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
366e0 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
366f0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
36700 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
36710 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
36720 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
36730 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
36740 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
36750 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
36760 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
36770 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
36780 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
36790 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
367a0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
367b0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
367c0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
367d0 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
367e0 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
367f0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
36800 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
36810 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
36820 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
36830 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
36840 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
36850 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
36860 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
36870 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
36880 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
36890 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
368a0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
368b0 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
368c0 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
368d0 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
368e0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
368f0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
36900 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
36910 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
36920 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
36930 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
36940 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36950 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
36960 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
36970 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
36980 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
36990 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
369a0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
369b0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
369c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
369d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
369e0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
369f0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
36a00 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
36a10 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
36a20 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
36a30 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36a50 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
36a60 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
36a70 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
36a80 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36a90 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
36aa0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
36ab0 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
36ac0 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
36ad0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36ae0 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
36af0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
36b00 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
36b10 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
36b20 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
36b30 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
36b40 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
36b50 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
36b60 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
36b70 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
36b80 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
36b90 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
36ba0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
36bb0 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
36bc0 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
36bd0 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
36be0 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
36bf0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
36c00 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
36c10 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
36c20 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
36c30 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
36c40 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
36c50 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
36c60 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
36c70 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
36c80 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
36c90 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
36ca0 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
36cb0 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
36cc0 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
36cd0 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
36ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
36cf0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
36d00 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
36d10 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
36d20 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
36d30 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
36d40 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
36d50 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
36d60 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
36d70 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
36d80 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
36d90 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
36da0 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
36db0 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
36dc0 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
36dd0 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
36de0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
36df0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
36e00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
36e10 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
36e20 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
36e30 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
36e40 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
36e50 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
36e60 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
36e70 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
36e80 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
36e90 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
36ea0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
36eb0 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
36ec0 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
36ed0 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
36ee0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
36ef0 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
36f00 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
36f10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
36f20 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
36f30 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
36f40 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
36f50 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
36f60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
36f70 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
36f80 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
36f90 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
36fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
36fb0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
36fc0 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
36fd0 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
36fe0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
36ff0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
37000 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
37010 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
37020 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
37030 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
37040 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
37050 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
37060 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
37070 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
37080 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
37090 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
370a0 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
370b0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
370c0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
370d0 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
370e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
370f0 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
37100 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
37110 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
37120 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
37130 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
37140 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
37150 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
37160 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
37170 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
37180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
37190 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
371a0 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
371b0 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
371c0 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
371d0 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
371e0 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
371f0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
37200 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
37210 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
37220 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
37230 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
37240 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
37250 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
37260 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
37270 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
37280 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
37290 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
372a0 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
372b0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
372c0 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
372d0 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
372e0 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
372f0 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
37300 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
37310 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
37320 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
37330 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
37340 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
37350 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
37360 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
37370 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
37380 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
37390 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
373a0 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
373b0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
373c0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
373d0 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
373e0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
373f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37400 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
37410 4c 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20  Load Statically 
37420 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e  Linked Extension
37430 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  s.**.** ^This in
37440 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
37450 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
37460 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37470 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65  invoked for.** e
37480 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73  ach new [databas
37490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
374a0 61 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20  at is created.  
374b0 54 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73  The idea here is
374c0 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50   that.** xEntryP
374d0 6f 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e  oint() is the en
374e0 74 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20  try point for a 
374f0 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
37500 64 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  d SQLite extensi
37510 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f  on.** that is to
37520 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
37530 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c  y loaded into al
37540 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  l new database c
37550 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  onnections..**.*
37560 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20  * ^(Even though 
37570 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f  the function pro
37580 74 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61  totype shows tha
37590 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  t xEntryPoint() 
375a0 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75  takes.** no argu
375b0 6d 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e  ments and return
375c0 73 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69  s void, SQLite i
375d0 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69  nvokes xEntryPoi
375e0 6e 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a  nt() with three.
375f0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64  ** arguments and
37600 20 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74   expects and int
37610 65 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69  eger result as i
37620 66 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20  f the signature 
37630 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20  of the.** entry 
37640 70 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66  point where as f
37650 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
37660 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
37670 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78  ** &nbsp;  int x
37680 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26  EntryPoint(.** &
37690 6e 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33  nbsp;    sqlite3
376a0 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20   *db,.** &nbsp; 
376b0 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a     const char **
376c0 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62  pzErrMsg,.** &nb
376d0 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72  sp;    const str
376e0 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
376f0 72 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b  routines *pThunk
37700 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a  .** &nbsp;  );.*
37710 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
37720 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66  uote>)^.**.** If
37730 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
37740 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74   routine encount
37750 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74  ers an error, it
37760 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a   should make *pz
37770 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20  ErrMsg.** point 
37780 74 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  to an appropriat
37790 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
377a0 28 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b  (obtained from [
377b0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
377c0 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72  )]).** and retur
377d0 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
377e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20   [error code].  
377f0 5e 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20  ^SQLite ensures 
37800 74 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a  that *pzErrMsg.*
37810 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65  * is NULL before
37820 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e   calling the xEn
37830 74 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51  tryPoint().  ^SQ
37840 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
37850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
37860 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73  e()] on *pzErrMs
37870 67 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f  g after xEntryPo
37880 69 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20  int() returns.  
37890 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72  ^If any.** xEntr
378a0 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73  yPoint() returns
378b0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b   an error, the [
378c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
378d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
378e0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
378f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63  te3_open_v2()] c
37900 61 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65  all that provoke
37910 64 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  d the xEntryPoin
37920 74 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a  t() will fail..*
37930 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
37940 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
37950 73 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20  sion(X) with an 
37960 65 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68  entry point X th
37970 61 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a  at is already.**
37980 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20   on the list of 
37990 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
379a0 69 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65  ions is a harmle
379b0 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e  ss no-op. ^No en
379c0 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c  try point.** wil
379d0 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65  l be called more
379e0 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65   than once for e
379f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
37a00 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  nection that is 
37a10 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  opened..**.** Se
37a20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
37a30 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
37a40 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  nsion()]..*/.int
37a50 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
37a60 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78  tension(void (*x
37a70 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64  EntryPoint)(void
37a80 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ));../*.** CAPI3
37a90 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d  REF: Reset Autom
37aa0 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c  atic Extension L
37ab0 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68  oading.**.** ^Th
37ac0 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73  is interface dis
37ad0 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61  ables all automa
37ae0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70  tic extensions p
37af0 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67  reviously.** reg
37b00 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
37b10 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
37b20 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  nsion()]..*/.voi
37b30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
37b40 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
37b50 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
37b60 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
37b70 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
37b80 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
37b90 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
37ba0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
37bb0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
37bc0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
37bd0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
37be0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
37bf0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
37c00 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
37c10 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
37c20 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
37c30 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
37c40 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
37c50 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
37c60 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
37c70 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
37c80 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
37c90 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
37ca0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
37cb0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
37cc0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
37cd0 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
37ce0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
37cf0 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
37d00 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
37d10 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
37d20 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
37d30 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
37d40 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
37d50 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
37d60 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
37d70 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
37d80 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
37d90 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
37da0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
37db0 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
37dc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37dd0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
37de0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
37df0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
37e00 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
37e10 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a  le module}.**.**
37e20 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
37e30 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
37e40 64 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  d a "virtual tab
37e50 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
37e60 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
37e70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
37e80 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
37e90 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
37ea0 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
37eb0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
37ec0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
37ed0 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61  .**.** ^A virtua
37ee0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
37ef0 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
37f00 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
37f10 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
37f20 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
37f30 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
37f40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
37f50 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
37f60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37f70 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
37f80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
37f90 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54  ule_v2()]..** ^T
37fa0 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20  he registration 
37fb0 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e  remains valid un
37fc0 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63  til it is replac
37fd0 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
37fe0 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75  t.** module or u
37ff0 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61  ntil the [databa
38000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
38010 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74  loses.  The cont
38020 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73  ent.** of this s
38030 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
38040 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69  t change while i
38050 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  t is registered 
38060 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61  with.** any data
38070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
38080 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
38090 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
380a0 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
380b0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
380c0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
380d0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
380e0 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
380f0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
38100 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
38110 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
38120 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
38130 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
38140 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
38150 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
38160 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
38170 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
38180 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
38190 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
381a0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
381b0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
381c0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
381d0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
381e0 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
381f0 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
38200 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
38210 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
38220 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
38230 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
38240 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
38250 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
38260 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
38270 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
38280 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
38290 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
382a0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
382b0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
382c0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
382d0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
382e0 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
382f0 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
38300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38310 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
38320 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
38330 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
38340 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
38350 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
38360 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
38370 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
38380 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
38390 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
383a0 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
383b0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
383c0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
383d0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
383e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
383f0 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
38400 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
38410 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
38420 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
38430 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
38440 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
38450 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
38460 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
38470 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
38480 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
38490 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
384a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
384b0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
384c0 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
384d0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
384e0 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
384f0 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
38500 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
38510 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
38520 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
38530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
38540 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
38550 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
38560 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
38570 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
38580 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
38590 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74   **ppArg);.  int
385a0 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
385b0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
385c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
385d0 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74  w);.  /* The met
385e0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
385f0 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
38600 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65  he sqlite_module
38610 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a   object. Those .
38620 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66    ** below are f
38630 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  or version 2 and
38640 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69   greater. */.  i
38650 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29  nt (*xSavepoint)
38660 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
38670 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  VTab, int);.  in
38680 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71  t (*xRelease)(sq
38690 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
386a0 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  b, int);.  int (
386b0 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71  *xRollbackTo)(sq
386c0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
386d0 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a  b, int);.};../*.
386e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
386f0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
38700 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
38710 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
38720 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
38730 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
38740 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
38750 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
38760 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
38770 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20  used as part.** 
38780 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
38790 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65  table] interface
387a0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
387b0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
387c0 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
387d0 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
387e0 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
387f0 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
38800 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
38810 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
38820 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
38830 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
38840 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
38850 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
38860 20 78 42 65 73