/ Hex Artifact Content
Login

Artifact 08a2d9a278ff0dfd65055a7ec9c599f7ae1a3c18:


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 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
16d0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
16e0: 4f 4e 5f 44 49 41 47 53 0a 2f 2a 0a 2a 2a 20 43  ON_DIAGS./*.** C
16f0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1700: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
1710: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
1720: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
1730: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
1740: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1750: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1760: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1770: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1780: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1790: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
17a0: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
17b0: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
17c0: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
17d0: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
17e0: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
17f0: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1800: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1810: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
1820: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1830: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1840: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
1850: 6c 6f 77 73 20 69 6e 74 65 72 61 74 69 6e 67 0a  lows interating.
1860: 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74  ** over the list
1870: 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74   of options that
1880: 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74   were defined at
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79   compile time by
18a0: 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68  .** returning th
18b0: 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74  e N-th compile t
18c0: 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e  ime option strin
18d0: 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74  g.  ^If N is out
18e0: 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71   of range,.** sq
18f0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1900: 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e  ion_get() return
1910: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1920: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
1930: 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d  .** prefix is om
1940: 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73  itted from any s
1950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1960: 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  by .** sqlite3_c
1970: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1980: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f  ()..**.** ^Suppo
1990: 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e  rt for the diagn
19a0: 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20  ostic functions 
19b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
19c0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20  ption_used().** 
19d0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
19e0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
19f0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62  may be omitted b
1a00: 79 20 73 70 65 63 69 66 69 6e 67 20 74 68 65 20  y specifing the 
1a10: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1a20: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1a30: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1a40: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1a50: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1a60: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1a90: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1aa0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1ab0: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1ac0: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1ad0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 20 2f 2a  nt N);.#endif /*
1b40: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b50: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b60: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1b70: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1b80: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1b90: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
1ba0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bb0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1bc0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1bd0: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1be0: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1bf0: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
1c00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1c10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1ca0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1cb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1cc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1ce0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cf0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1d00: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1d10: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d20: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d30: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d40: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d50: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d60: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d70: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d80: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d90: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1da0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1db0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1dc0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1dd0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1de0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1df0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1e00: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1e10: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e20: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e30: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e40: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e50: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e60: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e70: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e80: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e90: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1ea0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1eb0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ec0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1ed0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ee0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ef0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1f00: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1f10: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f20: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f30: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f40: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f50: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f60: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f70: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f80: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1fa0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1fb0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fc0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fd0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fe0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1ff0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2000: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2010: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2020: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2030: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2040: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2050: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2060: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2070: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2080: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
20a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
20b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20e0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20f0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2100: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2110: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2120: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2130: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2140: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2150: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2160: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2170: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2180: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2190: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
21a0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
21b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21c0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21d0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21e0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21f0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2200: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2210: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2220: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2230: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2240: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2250: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2260: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2270: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2280: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2290: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
22a0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
22b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22c0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22d0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22e0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22f0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2300: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2310: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2320: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2330: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2340: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2350: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2360: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2370: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2380: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2390: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
23a0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
23b0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23c0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23d0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23e0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23f0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2400: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
2410: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2420: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2430: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2440: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2450: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2460: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2470: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2480: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2490: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
24a0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
24b0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24c0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24d0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24f0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2500: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2510: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2520: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2530: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2540: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2550: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2560: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2570: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2580: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2590: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
25a0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
25b0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25c0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25d0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25f0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2600: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2610: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2620: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2630: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2640: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2650: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2660: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2670: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2680: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2690: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26a0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26b0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26c0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26d0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26e0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26f0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2700: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2710: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2720: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2730: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2740: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2750: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2760: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2770: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2780: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2790: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
27a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
27b0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27d0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27f0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2800: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2810: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2820: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2830: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2840: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2850: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2860: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2870: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
28a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
28b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28f0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2900: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2910: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2930: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2940: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2950: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2960: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2970: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2980: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2990: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
29a0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
29b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29c0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29d0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29f0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2a00: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2a10: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a20: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a40: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a50: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a60: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a70: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a80: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a90: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2aa0: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2ab0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2ac0: 20 73 75 63 63 65 73 73 66 75 6c 6c 6c 79 20 64   successfullly d
2ad0: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
2ae0: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
2af0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b00: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
2b10: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2b20: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b30: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2b40: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b50: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
2b60: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2b70: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2b80: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
2b90: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
2ba0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2bb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2bc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2bd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2be0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2bf0: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
2c00: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2c10: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2c20: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2c30: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2c40: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2c50: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
2c60: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
2c70: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
2c80: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
2ca0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
2cb0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2cc0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
2cd0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
2ce0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2cf0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
2d00: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
2d10: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2d20: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
2d30: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
2d40: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
2d50: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
2d60: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
2d70: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
2d80: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2d90: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
2da0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2db0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
2dc0: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
2dd0: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
2de0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
2df0: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2e00: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
2e10: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
2e20: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
2e30: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2e40: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2e50: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
2e60: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
2e70: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
2e80: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
2e90: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
2ea0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
2eb0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2ec0: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2ed0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2ee0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2ef0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2f00: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2f10: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f20: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2f30: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2f40: 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68  terface.**.** Th
2f50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2f60: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
2f70: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
2f80: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
2f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2fb0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2fc0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2fd0: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73  ,.** that allows
2fe0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2ff0: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20  to run multiple 
3000: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51  statements of SQ
3010: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76  L.** without hav
3020: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74  ing to use a lot
3030: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a   of C code. .**.
3040: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
3050: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
3060: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   runs zero or mo
3070: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  re UTF-8 encoded
3080: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ,.** semicolon-s
3090: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74  eparate SQL stat
30a0: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
30b0: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  to its 2nd argum
30c0: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63  ent,.** in the c
30d0: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
30e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30f0: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73  on] passed in as
3100: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75   its 1st.** argu
3110: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63  ment.  ^If the c
3120: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3130: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75   of the 3rd argu
3140: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
3150: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3160: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69   NULL, then it i
3170: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61  s invoked for ea
3180: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a  ch result row.**
3190: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74   coming out of t
31a0: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c  he evaluated SQL
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
31c0: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
31d0: 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  to.** to sqlite3
31e0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
31f0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
3200: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
3210: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3220: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3230: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3240: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3250: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3260: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3270: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3280: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3290: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
32a0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
32b0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
32c0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
32d0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
32e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
32f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3300: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3310: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3320: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3330: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3340: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3350: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3360: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3370: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3380: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3390: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
33a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
33b0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
33c0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
33d0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
33e0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
33f0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3400: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3410: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3420: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3430: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3440: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3450: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3460: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3470: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3480: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3490: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
34a0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
34b0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
34c0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
34d0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
34e0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
34f0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3500: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3510: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3520: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3530: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3540: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3550: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3560: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3570: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3580: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3590: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
35a0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
35b0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
35c0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
35d0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
35e0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
35f0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3600: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3610: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3620: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3630: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3640: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3650: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3660: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3670: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3680: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3690: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
36a0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
36b0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
36c0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
36d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
36e0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
36f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3700: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3710: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3720: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3730: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3740: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3750: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3760: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3770: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3780: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3790: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
37a0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
37b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37c0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
37d0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
37e0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
37f0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3800: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3810: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3820: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3830: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3840: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3850: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3860: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3870: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3880: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3890: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
38a0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
38b0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
38c0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
38d0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
38e0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
38f0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3900: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3910: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3920: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3930: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3940: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3950: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3970: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3980: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3990: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
39a0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
39b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
39c0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
39d0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
39e0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
39f0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a00: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3a10: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3a20: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3a30: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3a40: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3a50: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3a60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3a70: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3a80: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3a90: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3aa0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ab0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3ac0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3ad0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3ae0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3af0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3b00: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3b10: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3b20: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3b30: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3b40: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3b50: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3b60: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3b70: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3b80: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3b90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
3bc0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3bd0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
3be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bf0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
3c00: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
3c10: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3c20: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3c30: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3c40: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
3c50: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
3c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
3c90: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
3ca0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
3cb0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3cc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3cd0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3ce0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3cf0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3d00: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
3d10: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3d20: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3d30: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3d40: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
3d50: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
3d60: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
3d70: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
3d80: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
3d90: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
3da0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
3db0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
3dc0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3dd0: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3de0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3df0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e00: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3e10: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3e20: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3e30: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3e40: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3e50: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3e60: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
3e70: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
3e80: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
3e90: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
3ea0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
3eb0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3ed0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3ee0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3ef0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3f00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3f10: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3f20: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3f30: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3f40: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3f50: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3f60: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
3f70: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
3f80: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3f90: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
3fa0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
3fb0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
3fc0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
3ff0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4000: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4020: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4030: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4040: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4050: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4070: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4080: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40a0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
40b0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
40c0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
40d0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
40e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
40f0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4100: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4110: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4120: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4140: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4150: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4160: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4170: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4180: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4190: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
41a0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
41b0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
41c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
41d0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
41e0: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
41f0: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
4200: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
4210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
4220: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
4230: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
4240: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
4250: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
4260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
4270: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
4280: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
4290: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
42a0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
42b0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
42c0: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
42d0: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
42e0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4300: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
4310: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
4320: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4330: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4340: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4350: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4360: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4380: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4390: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
43a0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
43b0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
43c0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43d0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43e0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43f0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
4400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
4410: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
4420: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4430: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4440: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4450: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4460: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4470: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4480: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4490: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
44a0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
44b0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
44c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44d0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44e0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44f0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
4510: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
4520: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4530: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4560: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4570: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4580: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4590: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45a0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
45b0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
45c0: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45f0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4600: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4610: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4620: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4640: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4650: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4660: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4670: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4680: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4690: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
46a0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
46b0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
46c0: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46d0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46e0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46f0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
4700: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4710: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4720: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4730: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4740: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4750: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4760: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4770: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4780: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4790: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
47a0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
47b0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
47c0: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47d0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47e0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47f0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
4800: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
4810: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
4820: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4830: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4840: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4850: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4860: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4870: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4880: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4890: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
48a0: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
48b0: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
48c0: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48d0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48e0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48f0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
4900: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
4910: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4920: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4930: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4940: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4950: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4960: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4970: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4980: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4990: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
49a0: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
49b0: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
49c0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49d0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49e0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49f0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
4a00: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a10: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
4a20: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a30: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a40: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a50: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a60: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a70: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a80: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a90: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4aa0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4ab0: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4ac0: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4ad0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ae0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4af0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4b10: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b30: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b50: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b70: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b90: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4ba0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4bb0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4bc0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4bd0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4be0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bf0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4c00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4c10: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4c20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c30: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c50: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c70: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c90: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4ca0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4cb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4cc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4cd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4ce0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cf0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4d00: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4d10: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4d20: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d40: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d50: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d80: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4da0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4db0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dc0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4dd0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4de0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4df0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e00: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4e10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e40: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e50: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4eb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ec0: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ed0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4ee0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ef0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4f10: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f40: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4f50: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4f60: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c  TE_LOCKED | (1<<
4f70: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  8) )../*.** CAPI
4f80: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
4f90: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
4fa0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
4fb0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
4fc0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
4fd0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
4fe0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4ff0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5000: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5010: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5020: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5030: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
5040: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5050: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5080: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5090: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
50a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
50d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
50e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
50f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5110: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5120: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5130: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5140: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5170: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5180: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
51b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
51c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
51d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51e0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
51f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5220: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5230: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5240: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5260: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5270: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5280: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52a0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
52b0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
52c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
52d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
52f0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5300: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5320: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5330: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5340: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5360: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5370: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5380: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
53b0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
53c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
53d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53e0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
53f0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5400: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5410: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5430: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5440: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5450: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5490: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
54a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
54b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
54e0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
54f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5500: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5510: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5520: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5530: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5540: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
5550: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
5560: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5570: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
5580: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
5590: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
55a0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
55b0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
55c0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
55d0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
55e0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
55f0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
5600: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
5610: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
5620: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5630: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
5640: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5650: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
5660: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5670: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
5680: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5690: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
56a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
56b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
56c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
56d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
56e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
56f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5700: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5710: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5720: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5730: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5740: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5750: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5760: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
5770: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
5780: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5790: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
57a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
57b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
57c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
57d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
57e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
57f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5800: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5810: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5820: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5830: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5840: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5850: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
5860: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
5870: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
5880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5890: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
58a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
58d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5900: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5920: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5930: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5950: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
5960: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
59a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
59c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
59f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a10: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5a20: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5a50: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
5a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a70: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5a80: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5a90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5aa0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
5ab0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
5ac0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
5ad0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5ae0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5af0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
5b00: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
5b10: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
5b20: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
5b30: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
5b40: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5b50: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
5b60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5b70: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
5b80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5b90: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
5ba0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
5bb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5bc0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
5bd0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
5be0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
5bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5c00: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
5c10: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
5c20: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
5c30: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
5c40: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5c50: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
5c60: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
5c70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5c80: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5c90: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5ca0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5cb0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5cc0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5cd0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5ce0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5cf0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5d00: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5d10: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5d20: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
5d30: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5d40: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5d50: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5d60: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5d70: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5d80: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
5d90: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
5da0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
5db0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5dc0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
5dd0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
5de0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
5df0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5e00: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5e10: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5e20: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
5e30: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
5e40: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5e50: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5e60: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5e70: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5e80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5e90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5ea0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5eb0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5ee0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5ef0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5f00: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5f10: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
5f20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
5f30: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
5f40: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
5f50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
5f60: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
5f70: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
5f80: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
5f90: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
5fa0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
5fb0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
5fc0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
5fd0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
5fe0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
5ff0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
6000: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
6010: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
6020: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
6030: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6040: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
6050: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
6060: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
6070: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
6080: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
6090: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
60a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
60b0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
60c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
60d0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
60e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
60f0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
6100: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
6110: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
6120: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6130: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
6140: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
6150: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
6160: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
6170: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
6180: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
6190: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
61a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
61b0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
61c0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
61d0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
61e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
61f0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6200: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6210: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6220: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6230: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6240: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
6250: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
6260: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
6270: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
6280: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
6290: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
62a0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
62b0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f  .**.** If the xO
62c0: 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20  pen method sets 
62d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
62e0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
62f0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
6300: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
6310: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
6320: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
6330: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
6340: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
6350: 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72   the xOpen repor
6360: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
6370: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
6380: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
6390: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
63a0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
63b0: 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20  led xOpen.** is 
63c0: 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f  for the xOpen to
63d0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
63e0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
63f0: 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a  lement to NULL..
6400: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
6410: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
6420: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
6430: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
6440: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
6450: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
6460: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
6470: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
6480: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
6490: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
64a0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
64b0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
64c0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
64d0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
64e0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
64f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
6500: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
6510: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
6520: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
6530: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
6540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
6550: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
6560: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6570: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
6580: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
6590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
65a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
65b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
65c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
65e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6600: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
6610: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6620: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
6630: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
6640: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
6650: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
6660: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
6670: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
6680: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
6690: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
66a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
66b0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
66c0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
66d0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
66e0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
66f0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
6700: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
6710: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
6720: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
6730: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
6740: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
6750: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
6760: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
6770: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
6780: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
6790: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
67a0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
67b0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
67c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
67d0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
67e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
67f0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6800: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6810: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
6820: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
6830: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
6840: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
6850: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
6860: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
6870: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
6880: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
6890: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
68a0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
68b0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
68c0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
68d0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
68e0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
68f0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6900: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6910: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
6920: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
6930: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
6940: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
6950: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
6960: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
6970: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
6980: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
6990: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
69a0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
69b0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
69c0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
69d0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
69e0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
69f0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6a00: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6a10: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
6a20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6a30: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6a40: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6a50: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6a60: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
6a70: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
6a80: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
6a90: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
6aa0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
6ab0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
6ac0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
6ad0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
6ae0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
6af0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
6b00: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
6b10: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
6b20: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
6b30: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
6b40: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
6b50: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
6b60: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
6b70: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
6b80: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
6b90: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
6ba0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
6bb0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6bc0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
6bd0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
6be0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
6bf0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
6c00: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
6c10: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
6c20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6c30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
6c40: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6c50: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
6c60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6c70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
6c80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6c90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
6ca0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6cb0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
6cc0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6cd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
6ce0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6cf0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
6d00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6d20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6d40: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6d50: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6d60: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
6d70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6d80: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
6d90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6da0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6db0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6dc0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6dd0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6de0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6df0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6e00: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6e10: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6e20: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6e30: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6e40: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6e50: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6e60: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6e70: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6e80: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6e90: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6ea0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6eb0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6ec0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6ed0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6ee0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6ef0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6f00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6f10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6f20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6f30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6f40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6f50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6f70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6f80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6f90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6fa0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6fb0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6fc0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
6fd0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
6fe0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
6ff0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
7000: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
7010: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
7020: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
7030: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
7040: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
7050: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
7060: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
7070: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
7080: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
7090: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
70a0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
70b0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
70c0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
70d0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
70e0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
70f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7100: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
7110: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
7120: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7130: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
7140: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
7150: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
7160: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
7170: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
7180: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
7190: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
71a0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
71b0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
71c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
71d0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
71e0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
71f0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
7200: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
7210: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
7220: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
7230: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
7240: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7250: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
7260: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
7270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7280: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
7290: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
72d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
72e0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
72f0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
7300: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
7310: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
7320: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
7330: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7340: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
7350: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
7360: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
7370: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
7380: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7390: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
73a0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
73b0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
73c0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
73d0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
73e0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
73f0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
7400: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
7410: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
7420: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
7430: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
7440: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
7450: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
7460: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
7470: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7480: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
7490: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
74a0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
74b0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
74c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
74d0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
74e0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
74f0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7500: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7510: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7520: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7530: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7540: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
7550: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
7560: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
7570: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7580: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
7590: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
75a0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
75b0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
75c0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
75d0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
75e0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
75f0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
7600: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
7610: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
7620: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
7630: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
7640: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
7650: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
7660: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
7670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7680: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
7690: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
76a0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
76b0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
76c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
76d0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
76e0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
76f0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
7700: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a               4..
7710: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7720: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
7730: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
7740: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
7750: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
7760: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
7770: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
7780: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
7790: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
77a0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
77b0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
77c0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
77d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
77e0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
77f0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
7800: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
7810: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
7820: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
7830: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
7840: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
7850: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
7860: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
7870: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7880: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
7890: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
78a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
78b0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
78c0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
78d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
78e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
78f0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
7900: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
7910: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
7920: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
7930: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
7940: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
7950: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
7960: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
7970: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
7980: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
7990: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
79a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
79b0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
79c0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
79d0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
79e0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
79f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7a00: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
7a10: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
7a20: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
7a30: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
7a40: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
7a50: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
7a60: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
7a70: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
7a80: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
7a90: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
7aa0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
7ab0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
7ac0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
7ad0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
7ae0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
7af0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
7b00: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
7b10: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7b20: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
7b30: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
7b40: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
7b50: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
7b60: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
7b70: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
7b80: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
7b90: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
7ba0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
7bb0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
7bc0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
7bd0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
7be0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
7bf0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
7c00: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
7c10: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
7c20: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
7c30: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
7c40: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
7c50: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
7c60: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
7c70: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
7c80: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
7c90: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
7ca0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
7cb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
7cc0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
7cd0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7ce0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
7cf0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7d00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
7d10: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7d20: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7d30: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
7d40: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
7d50: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
7d60: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
7d70: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
7d80: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
7d90: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
7da0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
7db0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
7dc0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
7dd0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
7de0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
7df0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
7e00: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
7e10: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
7e20: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
7e30: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
7e40: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
7e50: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
7e60: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
7e70: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
7e80: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
7e90: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
7ea0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
7eb0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
7ec0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
7ed0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
7ee0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
7ef0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
7f00: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
7f10: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
7f20: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
7f30: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
7f40: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
7f50: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
7f60: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
7f70: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
7f80: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
7f90: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
7fa0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
7fb0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
7fc0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
7fd0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
7fe0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
7ff0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8000: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
8010: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
8020: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
8030: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
8040: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
8050: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
8060: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8070: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8080: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8090: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
80a0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65  e file.  Wheneve
80b0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
80c0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
80d0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
80e0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
80f0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
8100: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
8110: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
8120: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8130: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
8140: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8150: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
8160: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
8170: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
8180: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8190: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
81a0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
81b0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
81c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
81d0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
81e0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
81f0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
8200: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
8210: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
8220: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
8230: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
8240: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
8250: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
8260: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
8270: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
8280: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
8290: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
82a0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
82b0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  et..**.** SQLite
82c0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
82d0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
82e0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
82f0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
8300: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
8310: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
8320: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
8330: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
8340: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
8350: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8360: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
8370: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8380: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8390: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
83a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
83b0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83c0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
83d0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
83e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
83f0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
8400: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8410: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
8420: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NAL].** </ul>.**
8430: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
8440: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8450: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
8460: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
8470: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
8480: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
8490: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
84a0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
84b0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
84c0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
84d0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
84e0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
84f0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8500: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8510: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8520: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8530: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8540: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8550: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8560: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8570: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8580: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8590: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
85a0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
85b0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
85c0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
85d0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
85e0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
85f0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8600: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8610: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8620: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8630: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8640: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8650: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8660: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8670: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8680: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8690: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
86a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
86b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
86c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
86d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
86e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
86f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8700: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8710: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8720: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8730: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8740: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51  closed.  The [SQ
8750: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8760: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8770: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8780: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
8790: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
87a0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
87b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
87c0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
87d0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
87e0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
87f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
8800: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
8810: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
8820: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
8830: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
8840: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
8850: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
8860: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
8870: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
8880: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8890: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
88a0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
88b0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
88c0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
88d0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
88e0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
88f0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
8900: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
8910: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
8920: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
8930: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
8940: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
8950: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
8960: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
8970: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
8980: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74  access..**.** At
8990: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
89a0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
89b0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
89c0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
89d0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
89e0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
89f0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8a00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8a10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8a20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8a30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8a40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8a50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8a60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8a70: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
8a80: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
8a90: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
8aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
8ab0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
8ac0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
8ad0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8ae0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
8af0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
8b00: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
8b10: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
8b20: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
8b30: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
8b40: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
8b50: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
8b60: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
8b70: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
8b80: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
8b90: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
8ba0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
8bb0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54  en call..**.** T
8bc0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8bd0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
8be0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
8bf0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8c00: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8c10: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8c20: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
8c30: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8c40: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
8c50: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
8c60: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
8c70: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
8c80: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
8c90: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
8ca0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
8cb0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
8cc0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
8cd0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
8ce0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
8cf0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
8d00: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
8d10: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
8d20: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
8d30: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
8d40: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
8d50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
8d60: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
8d70: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
8d80: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
8d90: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
8da0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
8db0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
8dc0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
8dd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
8de0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
8df0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
8e00: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
8e10: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
8e20: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
8e30: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
8e40: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
8e50: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
8e60: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
8e70: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
8e80: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
8e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
8ea0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
8eb0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
8ec0: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
8ed0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
8ee0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
8ef0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
8f00: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
8f10: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
8f20: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
8f30: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
8f40: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8f50: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
8f60: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
8f70: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
8f80: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
8f90: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
8fa0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
8fb0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
8fc0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
8fd0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
8fe0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
8ff0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9000: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9010: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9020: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9030: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9040: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9050: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
9060: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
9070: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
9080: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
9090: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
90a0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
90b0: 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79  d time..**.*/.ty
90c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
90d0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
90e0: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  _vfs;.struct sql
90f0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
9100: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
9110: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
9120: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
9130: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  r */.  int szOsF
9140: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
9150: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
9160: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
9170: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
9180: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
9190: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
91a0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
91b0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
91c0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
91d0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
91e0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
91f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9200: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9210: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9220: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9230: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
9240: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9250: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
9260: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
9270: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
9280: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9290: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
92a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
92b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
92c0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
92d0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
92e0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
92f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9300: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9310: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9320: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9330: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9340: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9350: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
9360: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
9370: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
9380: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
9390: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
93a0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
93b0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
93c0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
93d0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
93e0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
93f0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9400: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9410: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9420: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9430: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
9440: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9450: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9460: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
9470: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
9480: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9490: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
94a0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
94b0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94c0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
94d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
94e0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
94f0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9500: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9510: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9520: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9530: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9540: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9550: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9560: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69   *);.  /* New fi
9570: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
9580: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
9590: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
95a0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
95b0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
95c0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
95d0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f  appens. */.};../
95e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
95f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
9600: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
9610: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
9620: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9630: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9640: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
9650: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
9660: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
9670: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
9680: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
9690: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
96a0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
96b0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
96c0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
96d0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
96e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
96f0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
9700: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
9710: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9720: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
9730: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9740: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
9750: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9760: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
9770: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
9780: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
9790: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
97a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
97b0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
97c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
97d0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
97e0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
97f0: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
9800: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9810: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
9820: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9830: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
9840: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9850: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
9860: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
9870: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
9880: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
9890: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
98a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
98b0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
98c0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
98d0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
98e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
98f0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
9900: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
9910: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
9920: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
9930: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9940: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
9950: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
9960: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
9970: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
9980: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
9990: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
99a0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
99b0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
99c0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
99d0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
99e0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
99f0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
9a00: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9a10: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
9a20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9a30: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
9a40: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
9a50: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
9a60: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9a70: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
9a80: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
9a90: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
9aa0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
9ab0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
9ac0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
9ad0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
9ae0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
9af0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
9b00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9b10: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
9b20: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
9b30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9b40: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
9b50: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
9b60: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
9b70: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
9b80: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
9b90: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9ba0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
9bb0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
9bc0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
9bd0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
9be0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9bf0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
9c00: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
9c10: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
9c20: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
9c30: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9c40: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
9c50: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
9c60: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
9c70: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
9c80: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9c90: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
9ca0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
9cb0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
9cc0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
9cd0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
9ce0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
9cf0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
9d00: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
9d10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
9d20: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
9d30: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
9d40: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
9d50: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
9d60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9d70: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
9d80: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
9d90: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
9da0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
9db0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
9dc0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
9dd0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9de0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
9df0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
9e00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9e10: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
9e20: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9e30: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9e40: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
9e50: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
9e60: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
9e70: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
9e80: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9e90: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
9ea0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
9eb0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
9ec0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
9ed0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
9ee0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
9ef0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
9f00: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
9f10: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
9f20: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
9f30: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
9f40: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
9f50: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
9f60: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
9f70: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
9f80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
9f90: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
9fa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9fb0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9fc0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9fd0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9fe0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9ff0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
a000: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
a010: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
a020: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
a030: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
a040: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
a050: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
a060: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
a070: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a080: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
a090: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
a0a0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
a0b0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
a0c0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
a0d0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
a0e0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
a0f0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
a100: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
a110: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
a120: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
a130: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
a140: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
a150: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
a160: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
a170: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
a180: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a190: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
a1a0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
a1b0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
a1c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a1d0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
a1e0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
a1f0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
a200: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
a210: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
a220: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
a230: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
a240: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
a250: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
a260: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
a270: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
a280: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
a290: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
a2a0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
a2b0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
a2c0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
a2d0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
a2e0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
a2f0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
a300: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
a310: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
a320: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
a330: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
a340: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
a350: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
a360: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
a370: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
a380: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
a390: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
a3a0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
a3b0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
a3c0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
a3d0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
a3e0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
a3f0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a400: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
a410: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
a420: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
a430: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
a440: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
a450: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
a460: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
a470: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
a480: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
a490: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
a4a0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
a4b0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
a4c0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
a4d0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
a4e0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
a4f0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
a500: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a510: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
a520: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
a530: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
a540: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a550: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
a560: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a570: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
a580: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
a590: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
a5a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
a5b0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
a5c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
a5d0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
a5e0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
a5f0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
a600: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
a610: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
a620: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
a630: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
a640: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
a650: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
a660: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a670: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
a680: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
a690: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
a6a0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
a6b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a6c0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
a6d0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
a6e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
a6f0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
a700: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
a710: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
a720: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
a730: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
a740: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
a750: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
a760: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
a770: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
a780: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
a790: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
a7a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
a7b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a7c0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
a7d0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
a7e0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
a7f0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
a800: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
a810: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
a820: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a830: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
a840: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
a850: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
a860: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
a870: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
a880: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a890: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
a8a0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
a8b0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
a8c0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
a8d0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
a8e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
a8f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
a900: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
a910: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
a920: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
a930: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a940: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a950: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a960: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a970: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a980: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a990: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a9a0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a9b0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a9c0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a9d0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a9e0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a9f0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
aa00: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
aa10: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
aa20: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
aa30: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
aa40: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
aa50: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
aa60: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
aa70: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
aa80: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
aa90: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
aaa0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
aab0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
aac0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
aad0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
aae0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
aaf0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
ab00: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
ab10: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
ab20: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
ab30: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
ab40: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
ab50: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
ab60: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
ab70: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ab80: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ab90: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
aba0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
abb0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
abc0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
abd0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
abe0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
abf0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
ac00: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ac10: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
ac20: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
ac30: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
ac40: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
ac50: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
ac60: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
ac70: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
ac80: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
ac90: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
aca0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
acb0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
acc0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
acd0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
ace0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
acf0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
ad00: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ad10: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
ad20: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
ad30: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
ad40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ad50: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
ad60: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
ad70: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
ad80: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
ad90: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
ada0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
adb0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
adc0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
add0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
ade0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
adf0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
ae00: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ae10: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
ae20: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
ae30: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
ae40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ae50: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
ae60: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
ae70: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
ae80: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
ae90: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
aea0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
aeb0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
aec0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
aed0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
aee0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
aef0: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
af00: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
af10: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
af20: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
af30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
af40: 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ns.** EXPERIMENT
af50: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  AL.**.** The sql
af60: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
af70: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
af80: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
af90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
afa0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
afb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
afc0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
afd0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
afe0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
aff0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
b000: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
b010: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
b020: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
b030: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
b040: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
b050: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
b060: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b070: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
b080: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
b090: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
b0a0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
b0b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
b0c0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
b0d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
b0e0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
b0f0: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
b100: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
b110: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
b120: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
b130: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b140: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
b150: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
b160: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
b170: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
b180: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
b190: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
b1a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b1b0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
b1c0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
b1d0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
b1e0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
b1f0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
b200: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
b210: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
b220: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
b230: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
b240: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
b250: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
b260: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
b270: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
b280: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
b290: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
b2a0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
b2b0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
b2c0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
b2d0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
b2e0: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
b2f0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
b300: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b310: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
b320: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
b330: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
b340: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
b350: 75 74 69 6e 65 73 0a 2a 2a 20 45 58 50 45 52 49  utines.** EXPERI
b360: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
b370: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b380: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
b390: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
b3a0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
b3b0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
b3c0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b3d0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
b3e0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
b3f0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
b400: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
b410: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
b420: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
b430: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b440: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
b450: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
b460: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b470: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
b480: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
b490: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
b4a0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
b4b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
b4c0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
b4d0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
b4e0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b4f0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
b500: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
b510: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b520: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
b530: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
b540: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
b550: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
b560: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
b570: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
b580: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
b590: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
b5a0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
b5b0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
b5c0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
b5d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
b5e0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
b5f0: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
b600: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
b610: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
b620: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
b630: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
b640: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
b650: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
b660: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
b670: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
b680: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
b690: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
b6a0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
b6b0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
b6c0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
b6d0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
b6e0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
b6f0: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
b700: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
b710: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
b720: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
b730: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
b740: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
b750: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
b760: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
b770: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
b780: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
b790: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
b7a0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
b7b0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
b7c0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
b7d0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
b7e0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
b7f0: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
b800: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
b810: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
b820: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
b830: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
b840: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c  ry..** The xReal
b850: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  loc method must 
b860: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f  work like reallo
b870: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61  c() from the sta
b880: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a  ndard C library.
b890: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65  ** with the exce
b8a0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68  ption that if th
b8b0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
b8c0: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73  t to xRealloc is
b8d0: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c   zero,.** xReall
b8e0: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d  oc must be a no-
b8f0: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74  op - it must not
b900: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c   perform any all
b910: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65  ocation or.** de
b920: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51  allocation.  ^SQ
b930: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
b940: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
b950: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
b960: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
b970: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
b980: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
b990: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
b9a0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73  ** And so in cas
b9b0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75  es where xRoundu
b9c0: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  p always returns
b9d0: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
b9e0: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  er,.** xRealloc 
b9f0: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63  can perform exac
ba00: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64  tly as the stand
ba10: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c  ard library real
ba20: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69  loc() and.** sti
ba30: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61  ll be in complia
ba40: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70  nce with this sp
ba50: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a  ecification..**.
ba60: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
ba70: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
ba80: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
ba90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
baa0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
bab0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
bac0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
bad0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
bae0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
baf0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
bb00: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
bb10: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
bb20: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
bb30: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
bb40: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
bb50: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
bb60: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
bb70: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
bb80: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
bb90: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
bba0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
bbb0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
bbc0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
bbd0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
bbe0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
bbf0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
bc00: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
bc10: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
bc20: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
bc30: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
bc40: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
bc50: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
bc60: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
bc70: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
bc80: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
bc90: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
bca0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
bcb0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
bcc0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
bcd0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
bce0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
bcf0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
bd00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bd10: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
bd20: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
bd30: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
bd40: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bd50: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
bd60: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
bd70: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
bd80: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
bd90: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
bda0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
bdb0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
bdc0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
bdd0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
bde0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
bdf0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
be00: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
be10: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
be20: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
be30: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
be40: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
be50: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
be60: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
be70: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
be80: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
be90: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
bea0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
beb0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
bec0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
bed0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
bee0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
bef0: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
bf00: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
bf10: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
bf20: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
bf30: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
bf40: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
bf50: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
bf60: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
bf70: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
bf80: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
bf90: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
bfa0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
bfb0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
bfc0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
bfd0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
bfe0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
bff0: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
c000: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c010: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
c020: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
c030: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
c040: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
c050: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
c060: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
c070: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
c080: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
c090: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
c0a0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
c0b0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
c0c0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
c0d0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
c0e0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
c0f0: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
c100: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
c110: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
c120: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
c130: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
c140: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
c150: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
c160: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
c170: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c180: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c190: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
c1a0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
c1b0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c1c0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
c1d0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
c1e0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
c1f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
c200: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
c210: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
c220: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
c230: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
c240: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
c250: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
c260: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
c270: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
c280: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
c290: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
c2a0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
c2b0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
c2c0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
c2d0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
c2e0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
c2f0: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
c300: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
c310: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
c320: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
c330: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
c340: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
c350: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
c360: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
c370: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
c380: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
c390: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
c3a0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
c3b0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
c3c0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
c3d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
c3e0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
c3f0: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
c400: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
c410: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
c420: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
c430: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
c440: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
c450: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
c460: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
c470: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
c480: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
c490: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c4a0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
c4b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
c4c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
c4d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c4e0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
c4f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
c500: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
c510: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
c520: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c530: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
c540: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
c550: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
c560: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
c570: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
c580: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c590: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
c5a0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
c5b0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
c5c0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
c5d0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
c5e0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
c5f0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
c600: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
c610: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
c620: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c630: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
c640: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
c650: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c660: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
c670: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
c680: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
c690: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
c6a0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
c6b0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
c6c0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
c6d0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
c6e0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
c6f0: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
c700: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
c710: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
c720: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
c730: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
c740: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
c750: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
c760: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
c770: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
c780: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
c790: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
c7a0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
c7b0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
c7c0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
c7d0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
c7e0: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
c7f0: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
c800: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
c810: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
c820: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
c830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
c840: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
c850: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
c860: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
c870: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
c880: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
c890: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c8a0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
c8b0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c8c0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
c8d0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
c8e0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
c8f0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
c900: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
c910: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
c920: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
c930: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
c940: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
c950: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
c960: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
c970: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c980: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
c990: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
c9a0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c9b0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
c9c0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
c9d0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
c9e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c9f0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
ca00: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
ca10: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
ca20: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
ca30: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
ca40: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
ca50: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
ca60: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
ca70: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
ca80: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
ca90: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
caa0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
cab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
cac0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
cad0: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
cae0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
caf0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
cb00: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
cb10: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
cb20: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
cb30: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
cb40: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
cb50: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
cb60: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
cb70: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
cb80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
cb90: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
cba0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
cbb0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
cbc0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
cbd0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
cbe0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
cbf0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
cc00: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
cc10: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
cc20: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
cc30: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
cc40: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
cc50: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
cc60: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
cc70: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
cc80: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
cc90: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
cca0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
ccb0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
ccc0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
ccd0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
cce0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
ccf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
cd00: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
cd10: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
cd20: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
cd30: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
cd40: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
cd50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
cd60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
cd70: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
cd80: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
cd90: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
cda0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
cdb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cdc0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
cdd0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
cde0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
cdf0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
ce00: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
ce10: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
ce20: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
ce30: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
ce40: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
ce50: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
ce60: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
ce70: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
ce80: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
ce90: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
cea0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
ceb0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
cec0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
ced0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
cee0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
cef0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
cf00: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
cf10: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
cf20: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
cf30: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
cf40: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
cf50: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
cf60: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
cf70: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
cf80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
cf90: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
cfa0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cfb0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
cfc0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
cfd0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
cfe0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
cff0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
d000: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
d010: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
d020: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
d030: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
d040: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
d050: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
d060: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
d070: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
d080: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
d090: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
d0a0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d0b0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
d0c0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
d0d0: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
d0e0: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
d0f0: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
d100: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
d110: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d120: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
d130: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
d140: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d150: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
d160: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d170: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
d180: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
d190: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
d1a0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d1b0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d1c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
d1d0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
d1e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
d1f0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d200: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
d210: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
d220: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
d230: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
d240: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
d250: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
d260: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
d270: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
d280: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
d290: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
d2a0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
d2b0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
d2c0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
d2d0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
d2e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d2f0: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
d300: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
d310: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
d320: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
d330: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d340: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
d350: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
d360: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
d370: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
d380: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
d390: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
d3a0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
d3b0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
d3c0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
d3d0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
d3e0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
d3f0: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
d400: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
d410: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
d420: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
d430: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
d440: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
d450: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
d460: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
d470: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
d480: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
d490: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
d4a0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
d4b0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
d4c0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
d4d0: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
d4e0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
d4f0: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
d500: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
d510: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
d520: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
d530: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
d540: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
d550: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
d560: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
d570: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
d580: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
d590: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
d5a0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d5b0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
d5c0: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
d5d0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d5e0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
d5f0: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
d600: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
d610: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
d620: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
d630: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
d640: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
d650: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
d660: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
d670: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
d680: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
d690: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
d6a0: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63   which the scrac
d6b0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
d6c0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
d6d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
d6e0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
d6f0: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
d700: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
d710: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
d720: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
d730: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
d740: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
d750: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
d760: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
d770: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
d780: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
d790: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
d7a0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
d7b0: 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74  uired due to int
d7c0: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a  ernal overhead..
d7d0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
d7e0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
d7f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
d800: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
d810: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
d820: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
d830: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
d840: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
d850: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
d860: 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72  ratch buffer per
d870: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
d880: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
d890: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20  to the expected 
d8a0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
d8b0: 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c  f threads.  ^SQL
d8c0: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
d8d0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
d8e0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
d8f0: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74  is more than 6 t
d900: 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
d910: 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20  e.** page size. 
d920: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
d930: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
d940: 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  l scratch memory
d950: 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74   beyond .** what
d960: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
d970: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
d980: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
d990: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
d9a0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
d9b0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
d9c0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
d9d0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d9e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
d9f0: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
da00: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
da10: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
da20: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
da30: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
da40: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
da50: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
da60: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
da70: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
da80: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e  e implemenation.
da90: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
daa0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
dab0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
dac0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
dad0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
dae0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
daf0: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
db00: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
db10: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f  FIG_PCACHE optio
db20: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
db30: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
db40: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
db50: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
db60: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
db70: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
db80: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
db90: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
dba0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
dbb0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
dbc0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
dbd0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
dbe0: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
dbf0: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
dc00: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
dc10: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
dc20: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
dc30: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
dc40: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
dc50: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
dc60: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
dc70: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
dc80: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
dc90: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
dca0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
dcb0: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
dcc0: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
dcd0: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
dce0: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
dcf0: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
dd00: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
dd10: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
dd20: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
dd30: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
dd40: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
dd50: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
dd60: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
dd70: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
dd80: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
dd90: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
dda0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
ddb0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
ddc0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
ddd0: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
dde0: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
ddf0: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
de00: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
de10: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
de20: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
de30: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
de40: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
de50: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
de60: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
de70: 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  space..** ^The i
de80: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
de90: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d  ght use one or m
dea0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66  ore of the N buf
deb0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a  fers to hold .**
dec0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   memory accounti
ded0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  ng information. 
dee0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
def0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
df00: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
df10: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
df20: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
df30: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
df40: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
df50: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
df60: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
df70: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
df80: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
df90: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
dfa0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
dfb0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
dfc0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
dfd0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
dfe0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
dff0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e000: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
e010: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
e020: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
e030: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
e040: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
e050: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
e060: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
e070: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
e080: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
e090: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
e0a0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
e0b0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
e0c0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
e0d0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
e0e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
e0f0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
e100: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
e110: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
e120: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
e130: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
e140: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
e150: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
e160: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
e170: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
e180: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
e190: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
e1a0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
e1b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e1c0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
e1d0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
e1e0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
e1f0: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
e200: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
e210: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
e220: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
e230: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
e240: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
e250: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
e260: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
e270: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
e280: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
e290: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
e2a0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
e2b0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
e2c0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
e2d0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
e2e0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
e2f0: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
e300: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
e310: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
e320: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
e330: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e340: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
e350: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e360: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e370: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e380: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e390: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e3a0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e3b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
e3c0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
e3d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
e3e0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
e3f0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
e400: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
e410: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
e420: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
e430: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
e440: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
e450: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
e460: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
e470: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
e480: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
e490: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
e4a0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
e4b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
e4c0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
e4d0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
e4e0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
e4f0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
e500: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
e510: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
e520: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
e530: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
e540: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
e550: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
e560: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
e570: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
e580: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
e590: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
e5a0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e5b0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
e5c0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
e5d0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
e5e0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
e5f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e600: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
e610: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e620: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e630: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e640: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e650: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e660: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e670: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
e680: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e690: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
e6a0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
e6b0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e6c0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e6d0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e6e0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
e6f0: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
e700: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
e710: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
e720: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
e730: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
e740: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
e750: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
e760: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
e770: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
e780: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
e790: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
e7a0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
e7b0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e7c0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
e7d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
e7e0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e7f0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
e800: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
e810: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
e820: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
e830: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
e840: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
e850: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
e860: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e870: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
e880: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
e890: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
e8a0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
e8b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
e8c0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
e8d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e8e0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
e8f0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
e900: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
e910: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
e920: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
e930: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
e940: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
e950: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
e960: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
e970: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
e980: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
e990: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
e9a0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
e9b0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
e9c0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
e9d0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
e9e0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e9f0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
ea00: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
ea10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ea20: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
ea30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
ea40: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
ea50: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
ea60: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
ea70: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
ea80: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
ea90: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
eaa0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
eab0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
eac0: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
ead0: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
eae0: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
eaf0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
eb00: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
eb10: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
eb20: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
eb30: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
eb40: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
eb50: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
eb60: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
eb70: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
eb80: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
eb90: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
eba0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
ebb0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
ebc0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
ebd0: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
ebe0: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
ebf0: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
ec00: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
ec10: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
ec20: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
ec30: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
ec40: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
ec50: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
ec60: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
ec70: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ec80: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ec90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
eca0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
ecb0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
ecc0: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
ecd0: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
ece0: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
ecf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
ed00: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
ed10: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
ed20: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
ed30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
ed40: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
ed50: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
ed60: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
ed70: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
ed80: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
ed90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
eda0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
edb0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
edc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
edd0: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
ede0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
edf0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
ee00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ee10: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
ee20: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
ee30: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
ee40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ee50: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
ee60: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
ee70: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
ee80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ee90: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
eea0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
eeb0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
eec0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
eed0: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
eee0: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
eef0: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
ef00: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
ef10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ef20: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
ef30: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
ef40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ef50: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
ef60: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
ef70: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
ef80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ef90: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
efa0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
efb0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
efc0: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
efd0: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
efe0: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
eff0: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
f000: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
f010: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f020: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
f030: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
f040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f050: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
f060: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
f070: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
f080: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f090: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
f0a0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
f0b0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f0c0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f0d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
f0e0: 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
f0f0: 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
f100: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
f110: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
f120: 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 45 58 50  n Options.** EXP
f130: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
f140: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
f150: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
f160: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
f170: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
f180: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
f190: 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
f1a0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
f1b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
f1c0: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
f1d0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
f1e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f1f0: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
f200: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
f210: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
f220: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
f230: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f240: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
f250: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
f260: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
f270: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
f280: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
f290: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
f2a0: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
f2b0: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
f2c0: 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
f2d0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f2e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
f2f0: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
f300: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
f310: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
f320: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
f330: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
f340: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
f350: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
f360: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
f370: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f380: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
f390: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
f3a0: 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
f3b0: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
f3c0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
f3d0: 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
f3e0: 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
f3f0: 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
f400: 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
f410: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f420: 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
f430: 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
f440: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f450: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
f460: 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
f470: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d  ointer to an mem
f480: 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
f490: 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
f4a0: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
f4b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
f4c0: 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
f4d0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
f4e0: 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
f4f0: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
f500: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
f510: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
f520: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
f530: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
f540: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f550: 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
f560: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
f570: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
f580: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
f590: 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
f5a0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
f5b0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
f5c0: 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
f5d0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
f5e0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
f5f0: 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
f600: 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
f610: 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
f620: 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
f630: 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
f640: 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
f650: 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
f660: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
f670: 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
f680: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
f690: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
f6a0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f6b0: 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
f6c0: 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
f6d0: 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
f6e0: 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
f6f0: 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
f700: 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f  er.** multiple o
f710: 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20  f 8.  See also: 
f720: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
f730: 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a  OOKASIDE]</dd>.*
f740: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
f750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
f760: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
f770: 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
f780: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f  * int int */.../
f790: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
f7a0: 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
f7b0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
f7c0: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
f7d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
f7e0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
f7f0: 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
f800: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
f810: 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
f820: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
f830: 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
f840: 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
f850: 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
f860: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
f870: 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
f880: 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
f890: 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
f8a0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
f8b0: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
f8c0: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
f8d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f8e0: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
f8f0: 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
f900: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
f910: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
f920: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
f930: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
f940: 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
f950: 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
f960: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
f970: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
f980: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
f990: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
f9a0: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
f9b0: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
f9c0: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
f9d0: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
f9e0: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
f9f0: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
fa00: 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
fa10: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
fa20: 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
fa30: 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
fa40: 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
fa50: 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
fa60: 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
fa70: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
fa80: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
fa90: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
faa0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
fab0: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
fac0: 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
fad0: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
fae0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
faf0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
fb00: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
fb10: 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
fb20: 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
fb30: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
fb40: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
fb50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
fb60: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
fb70: 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
fb80: 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
fb90: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
fba0: 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64   then the [rowid
fbb0: 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
fbc0: 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75  d.** row is retu
fbd0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
fbe0: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
fbf0: 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72  the trigger is r
fc00: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
fc10: 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
fc20: 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
fc30: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
fc40: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  y this routine.*
fc50: 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  * reverts to the
fc60: 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
fc70: 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  rted before the 
fc80: 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e  trigger fired.)^
fc90: 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
fca0: 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
fcb0: 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
fcc0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
fcd0: 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
fce0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
fcf0: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
fd00: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
fd10: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
fd20: 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
fd30: 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
fd40: 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
fd50: 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
fd60: 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
fd70: 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
fd80: 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
fd90: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
fda0: 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
fdb0: 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
fdc0: 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
fdd0: 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
fde0: 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
fdf0: 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
fe00: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
fe10: 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
fe20: 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
fe30: 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
fe40: 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
fe50: 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
fe60: 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
fe70: 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
fe80: 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
fe90: 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
fea0: 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
feb0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
fec0: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
fed0: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
fee0: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
fef0: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
ff00: 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
ff10: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
ff20: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
ff30: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
ff40: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
ff50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
ff60: 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
ff70: 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
ff80: 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
ff90: 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
ffa0: 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
ffb0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
ffc0: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
ffd0: 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
ffe0: 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
fff0: 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
10000 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
10010 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
10020 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
10030 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
10040 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
10050 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
10060 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
10070 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
10080 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10090 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
100a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
100b0 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
100c0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
100d0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
100e0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
100f0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
10100 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
10110 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
10120 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
10130 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
10140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10150 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
10160 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
10170 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
10180 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
10190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
101a0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
101b0 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
101c0 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
101d0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
101e0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
101f0 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
10200 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
10210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10220 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
10230 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
10240 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
10250 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
10260 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
10270 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
10280 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
10290 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
102a0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
102b0 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
102c0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
102d0 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
102e0 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
102f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
10300 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
10310 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
10320 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
10330 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
10340 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
10350 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
10360 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
10370 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
10380 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
10390 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
103a0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
103b0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
103c0 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
103d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
103e0 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
103f0 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
10400 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
10410 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
10420 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
10430 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
10440 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
10450 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
10460 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
10470 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
10480 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
10490 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
104a0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
104b0 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
104c0 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
104d0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
104e0 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
104f0 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
10500 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
10510 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
10520 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
10530 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
10540 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
10550 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
10560 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
10570 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
10580 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
10590 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
105a0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
105b0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
105c0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
105d0 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
105e0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
105f0 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
10600 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
10610 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
10620 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
10630 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
10640 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
10650 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
10660 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
10670 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
10680 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
10690 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
106a0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
106b0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
106c0 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
106d0 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
106e0 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
106f0 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
10700 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
10710 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
10720 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
10730 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
10740 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
10750 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
10760 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
10770 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
10780 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
10790 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
107a0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
107b0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
107c0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
107d0 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
107e0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
107f0 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
10800 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
10810 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
10820 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
10830 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
10840 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
10850 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
10860 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
10870 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
10880 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
10890 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
108a0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
108b0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
108c0 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
108d0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
108e0 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
108f0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
10900 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
10910 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
10920 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
10930 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
10940 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
10950 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
10960 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
10970 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
10980 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
10990 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
109a0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
109b0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
109c0 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
109d0 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
109e0 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
109f0 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
10a00 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
10a10 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
10a20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
10a30 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
10a40 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
10a50 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
10a60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
10a70 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
10a80 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
10a90 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
10aa0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
10ab0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
10ac0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
10ad0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
10ae0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
10af0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
10b00 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
10b10 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
10b20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10b30 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
10b40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10b50 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
10b60 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
10b70 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
10b80 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10b90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
10ba0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
10bb0 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
10bc0 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
10bd0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
10be0 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
10bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10c00 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
10c10 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
10c20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
10c30 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
10c40 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
10c50 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
10c60 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
10c70 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
10c80 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
10c90 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
10ca0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
10cb0 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
10cc0 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
10cd0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
10ce0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
10cf0 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
10d00 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
10d10 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
10d20 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
10d30 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
10d40 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
10d50 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
10d60 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
10d70 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
10d80 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
10d90 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
10da0 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
10db0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
10dc0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
10dd0 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
10de0 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
10df0 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
10e00 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
10e10 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
10e20 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
10e30 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
10e40 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
10e50 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
10e60 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
10e70 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
10e80 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
10e90 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
10ea0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
10eb0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
10ec0 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
10ed0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
10ee0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
10ef0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
10f00 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
10f10 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
10f20 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
10f30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
10f40 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
10f50 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
10f60 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
10f70 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
10f80 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
10f90 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
10fa0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
10fb0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
10fc0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
10fd0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
10fe0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
10ff0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
11000 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
11010 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
11020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
11030 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
11040 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
11050 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11060 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
11070 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
11080 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
11090 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
110a0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
110b0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
110c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
110d0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
110e0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
110f0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
11100 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
11110 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
11120 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
11130 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
11140 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
11150 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
11160 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
11170 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
11180 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
11190 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
111a0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
111b0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
111c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
111d0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
111e0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
111f0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
11200 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
11210 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
11220 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11230 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
11240 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
11250 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
11260 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11270 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
11280 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
11290 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
112a0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
112b0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
112c0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
112d0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
112e0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
112f0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
11300 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
11310 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
11320 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
11330 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
11340 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
11350 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
11360 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
11370 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
11380 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
11390 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
113a0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
113b0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
113c0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
113d0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
113e0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
113f0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
11400 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
11410 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
11420 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
11430 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
11440 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
11450 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
11460 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
11470 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
11480 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
11490 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
114a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
114b0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
114c0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
114d0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
114e0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
114f0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
11500 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
11510 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
11520 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
11530 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
11540 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
11550 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
11560 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
11570 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
11580 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11590 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
115a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
115b0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
115c0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
115d0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
115e0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
115f0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
11600 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
11610 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
11620 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
11630 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11640 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
11650 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
11660 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
11670 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
11680 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
11690 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
116a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
116b0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
116c0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
116d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
116e0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
116f0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
11700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
11710 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
11720 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
11730 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
11740 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
11750 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
11760 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
11770 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
11780 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
11790 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
117a0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
117b0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
117c0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
117d0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
117e0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
117f0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
11800 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
11810 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
11820 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
11830 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
11840 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
11850 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
11860 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
11870 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
11880 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
11890 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
118a0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
118b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
118c0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
118d0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
118e0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
118f0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
11900 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
11910 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
11920 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
11930 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
11940 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
11950 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
11960 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
11970 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
11980 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
11990 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
119a0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
119b0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
119c0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
119d0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
119e0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
119f0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
11a00 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
11a10 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
11a20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
11a30 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
11a40 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
11a50 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
11a60 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
11a70 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
11a80 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
11a90 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
11aa0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
11ab0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
11ac0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
11ad0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
11ae0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
11af0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
11b00 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
11b10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
11b20 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
11b30 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
11b40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
11b50 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
11b60 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
11b70 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
11b80 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
11b90 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
11ba0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
11bb0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
11bc0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
11bd0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
11be0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
11bf0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
11c00 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
11c10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
11c20 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
11c30 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
11c40 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
11c50 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
11c60 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
11c70 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
11c80 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
11c90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
11ca0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
11cb0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
11cc0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
11cd0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
11ce0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
11cf0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
11d00 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
11d10 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
11d20 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
11d30 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
11d40 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
11d50 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
11d60 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
11d70 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
11d80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
11d90 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
11da0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
11db0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
11dc0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
11dd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
11de0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
11df0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
11e00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
11e10 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
11e20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11e30 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
11e40 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
11e50 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
11e60 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
11e70 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
11e80 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
11e90 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
11ea0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
11eb0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
11ec0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
11ed0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
11ee0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
11ef0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
11f00 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
11f10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
11f20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
11f30 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
11f40 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
11f50 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
11f60 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
11f70 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
11f80 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
11f90 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
11fa0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
11fb0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
11fc0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
11fd0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
11fe0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
11ff0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
12000 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12010 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
12020 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
12030 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
12040 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
12050 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
12060 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
12070 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
12080 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12090 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
120a0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
120b0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
120c0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
120d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
120e0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
120f0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
12100 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
12110 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
12120 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
12130 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
12140 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
12150 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
12160 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
12170 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
12180 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
12190 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
121a0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
121b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
121c0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
121d0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
121e0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
121f0 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
12200 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
12210 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
12220 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
12230 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
12240 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
12250 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
12260 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
12270 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
12280 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
12290 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
122a0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
122b0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
122c0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
122d0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
122e0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
122f0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
12300 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12310 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
12320 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
12330 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
12340 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
12350 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
12360 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
12370 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
12380 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
12390 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
123a0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
123b0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
123c0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
123d0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
123e0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
123f0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
12400 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
12410 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
12420 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
12430 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
12440 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
12450 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
12460 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
12470 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
12480 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
12490 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
124a0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
124b0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
124c0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
124d0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
124e0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
124f0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
12500 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
12510 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
12520 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
12530 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
12540 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
12550 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
12560 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
12570 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
12580 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
12590 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
125a0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
125b0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
125c0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
125d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
125e0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
125f0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
12600 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
12610 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
12620 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
12630 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
12640 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
12650 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
12660 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
12670 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
12680 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
12690 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
126a0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
126b0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
126c0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
126d0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
126e0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
126f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
12700 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
12710 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
12720 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
12730 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
12740 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
12750 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
12760 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
12770 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
12780 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
12790 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
127a0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
127b0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
127c0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
127d0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
127e0 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
127f0 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
12800 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
12810 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
12820 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
12830 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
12840 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
12850 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
12860 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12870 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
12880 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
12890 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
128a0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
128b0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
128c0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
128d0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
128e0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
128f0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
12900 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
12910 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
12920 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
12930 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
12940 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
12950 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
12960 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
12970 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
12980 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
12990 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
129a0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
129b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
129c0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
129d0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
129e0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
129f0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
12a00 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
12a10 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
12a20 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
12a30 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
12a40 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
12a50 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
12a60 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
12a70 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
12a80 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
12a90 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
12aa0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
12ab0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
12ac0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
12ad0 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
12ae0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
12af0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
12b00 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
12b10 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
12b20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
12b30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
12b40 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
12b50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12b60 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
12b70 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
12b80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12b90 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
12ba0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
12bb0 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
12bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12bd0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
12be0 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
12bf0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
12c00 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
12c10 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
12c20 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
12c30 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
12c40 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
12c50 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
12c60 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
12c70 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
12c80 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
12c90 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
12ca0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
12cb0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
12cc0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
12cd0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
12ce0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
12cf0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
12d00 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
12d10 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
12d20 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
12d30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
12d40 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
12d50 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
12d60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
12d70 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
12d80 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
12d90 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
12da0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
12db0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
12dc0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
12dd0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
12de0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
12df0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
12e00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
12e10 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
12e20 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12e30 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
12e40 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
12e50 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
12e60 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
12e70 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
12e80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
12e90 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
12ea0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
12eb0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
12ec0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
12ed0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
12ee0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12ef0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
12f00 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
12f10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12f20 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
12f30 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
12f40 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
12f50 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
12f60 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
12f70 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
12f80 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
12f90 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
12fa0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12fb0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
12fc0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
12fd0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
12fe0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
12ff0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
13000 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
13010 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
13020 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
13030 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
13040 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
13050 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
13060 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
13070 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
13080 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
13090 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
130a0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
130b0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
130c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
130d0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
130e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
130f0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
13100 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
13110 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
13120 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
13130 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
13140 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
13150 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
13160 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
13170 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
13180 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
13190 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
131a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
131b0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
131c0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
131d0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
131e0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
131f0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
13200 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
13210 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
13220 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
13230 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
13240 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
13250 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
13260 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
13270 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
13280 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
13290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
132a0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
132b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
132c0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
132d0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
132e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
132f0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
13300 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
13310 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
13320 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
13330 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
13340 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
13350 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
13360 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
13370 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
13380 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
13390 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
133a0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
133b0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
133c0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
133d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
133e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
133f0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
13400 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
13410 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
13420 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
13430 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
13440 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
13450 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
13460 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
13470 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
13480 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
13490 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
134a0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
134b0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
134c0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
134d0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
134e0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
134f0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
13500 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
13510 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
13520 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
13530 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
13540 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
13550 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
13560 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13570 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
13580 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
13590 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
135a0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
135b0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
135c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
135d0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
135e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
135f0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
13600 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13610 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
13620 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13630 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
13640 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
13650 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
13660 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
13670 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13680 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
13690 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
136a0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e>.**.** ^The sq
136b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
136c0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
136d0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
136e0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
136f0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
13700 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
13710 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
13720 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
13730 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
13740 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
13750 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
13760 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
13770 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
13780 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
13790 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
137a0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
137b0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
137c0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
137d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
137e0 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73  * it should pass
137f0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13800 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
13810 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
13820 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
13830 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
13840 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
13850 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
13860 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
13870 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
13880 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
13890 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
138a0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
138b0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
138c0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
138d0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
138e0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
138f0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
13900 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
13910 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
13920 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
13930 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
13940 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
13950 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13960 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
13970 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
13980 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
13990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
139a0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
139b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
139c0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
139d0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
139e0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
139f0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
13a00 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
13a10 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
13a20 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
13a30 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
13a40 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
13a50 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
13a60 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
13a70 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
13a80 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
13a90 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
13aa0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
13ab0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
13ac0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
13ad0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
13ae0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
13af0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
13b00 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ].)^.*/.int sqli
13b10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
13b20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
13b30 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
13b40 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
13b50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
13b60 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
13b70 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
13b80 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
13b90 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
13ba0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
13bb0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
13bc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
13bd0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
13be0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
13bf0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
13c00 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
13c10 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
13c20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
13c30 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
13c40 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
13c50 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
13c60 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
13c70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
13c80 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
13c90 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
13ca0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
13cb0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
13cc0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
13cd0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
13ce0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
13cf0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
13d00 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
13d10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
13d20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
13d30 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
13d40 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
13d50 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
13d60 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
13d70 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
13d80 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
13d90 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
13da0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
13db0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
13dc0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
13dd0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
13de0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
13df0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
13e00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
13e10 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
13e20 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
13e30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
13e40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13e50 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
13e60 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
13e70 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
13e80 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
13e90 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  tring..**.** ^(I
13ea0 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
13eb0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
13ec0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
13ed0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
13ee0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
13ef0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
13f00 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
13f10 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
13f20 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
13f30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13f40 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
13f50 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
13f60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13f70 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
13f80 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
13f90 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
13fa0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
13fb0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
13fc0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
13fd0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
13fe0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
13ff0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
14000 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
14010 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
14020 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
14030 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
14040 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
14050 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
14060 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
14070 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
14080 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
14090 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
140a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
140b0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
140c0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
140d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
140e0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
140f0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
14100 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
14110 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
14120 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
14130 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
14140 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
14150 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
14160 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
14170 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
14180 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
14190 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
141a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
141b0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
141c0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
141d0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
141e0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
141f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
14200 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
14210 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
14220 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
14230 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
14240 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
14250 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
14260 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
14270 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
14280 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
14290 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
142a0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
142b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
142c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
142d0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
142e0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
142f0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
14300 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
14310 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
14320 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
14330 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
14340 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
14350 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
14360 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
14370 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
14380 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
14390 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
143a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
143b0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
143c0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
143d0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
143e0 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
143f0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
14400 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
14410 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
14420 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
14430 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
14440 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
14450 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
14460 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
14470 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
14480 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
14490 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
144a0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
144b0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
144c0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
144d0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
144e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
144f0 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
14500 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
14510 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
14520 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
14530 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
14540 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
14550 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
14560 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
14570 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14580 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
14590 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
145a0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
145b0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
145c0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
145d0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
145e0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
145f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
14600 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
14610 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
14620 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
14630 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
14640 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
14650 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
14660 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
14670 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14680 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
14690 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
146a0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
146b0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
146c0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
146d0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
146e0 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
146f0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
14700 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14710 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
14720 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
14730 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
14740 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
14750 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
14760 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
14770 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
14780 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
14790 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
147a0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
147b0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
147c0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
147d0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
147e0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
147f0 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
14800 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
14810 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14820 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
14830 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
14840 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
14850 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
14860 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
14870 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
14880 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
14890 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
148a0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
148b0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
148c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
148d0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
148e0 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
148f0 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
14900 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
14910 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
14920 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
14930 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
14940 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
14950 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
14960 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
14970 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
14980 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
14990 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
149a0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
149b0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
149c0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
149d0 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
149e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
149f0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
14a00 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
14a10 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
14a20 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
14a30 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
14a40 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
14a50 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
14a60 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
14a70 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
14a80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14a90 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
14aa0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
14ab0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
14ac0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
14ad0 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
14ae0 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
14af0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
14b00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
14b10 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
14b20 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
14b30 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
14b40 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
14b50 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
14b60 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
14b70 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
14b80 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
14b90 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
14ba0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
14bb0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
14bc0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
14bd0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
14be0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
14bf0 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
14c00 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
14c10 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
14c20 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
14c30 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
14c40 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
14c50 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
14c60 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
14c70 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
14c80 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
14c90 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
14ca0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
14cb0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
14cc0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
14cd0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
14ce0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
14cf0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
14d00 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
14d10 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
14d20 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
14d30 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
14d40 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
14d50 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
14d60 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
14d70 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
14d80 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
14d90 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
14da0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
14db0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
14dc0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14dd0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
14de0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
14df0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
14e00 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
14e10 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
14e20 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
14e30 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
14e40 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
14e50 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
14e60 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
14e70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
14e80 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
14e90 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
14ea0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
14eb0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
14ec0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
14ed0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
14ee0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
14ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
14f00 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
14f10 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
14f20 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
14f30 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
14f40 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
14f50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
14f60 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
14f70 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
14f80 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
14f90 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
14fa0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
14fb0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
14fc0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
14fd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
14fe0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
14ff0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
15000 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
15010 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
15020 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
15030 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
15040 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
15050 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
15060 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
15070 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
15080 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
15090 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
150a0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
150b0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
150c0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
150d0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
150e0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
150f0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
15100 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
15110 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
15120 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
15130 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
15140 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
15150 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
15160 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
15170 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
15180 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
15190 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
151a0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
151b0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
151c0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
151d0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
151e0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
151f0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
15200 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
15210 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
15220 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
15230 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
15240 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
15250 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
15260 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
15270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
15280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
15290 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
152a0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
152b0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
152c0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
152d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
152e0 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
152f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
15300 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
15310 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
15320 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15330 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
15340 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
15350 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
15360 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
15370 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
15380 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
15390 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
153a0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
153b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
153c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
153d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
153e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
153f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
15400 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
15410 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
15420 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
15430 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
15440 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
15450 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
15460 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
15470 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
15480 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
15490 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
154a0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
154b0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
154c0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
154d0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
154e0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
154f0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
15500 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
15510 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
15520 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
15530 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
15540 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
15550 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
15560 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
15570 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
15580 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
15590 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
155a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
155b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
155c0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
155d0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
155e0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
155f0 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a   boundary..**.**
15600 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
15610 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
15620 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
15630 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
15640 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
15650 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
15660 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
15670 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
15680 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
15690 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
156a0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
156b0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
156c0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
156d0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
156e0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
156f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
15700 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
15710 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
15720 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
15730 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
15740 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
15750 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
15760 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
15770 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
15780 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
15790 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
157a0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
157b0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
157c0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
157d0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
157e0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
157f0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
15800 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
15810 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
15820 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
15830 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
15840 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
15850 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
15860 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
15870 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
15880 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
15890 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
158a0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
158b0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
158c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
158d0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
158e0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
158f0 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
15900 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
15910 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
15920 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
15930 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
15940 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
15950 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
15960 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
15970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
15980 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15990 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
159a0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
159b0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
159c0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
159d0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
159e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
159f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
15a00 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
15a10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
15a20 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
15a30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15a40 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
15a50 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
15a60 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
15a70 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
15a80 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
15a90 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
15aa0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
15ab0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
15ac0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
15ad0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
15ae0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
15af0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
15b00 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
15b10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15b20 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
15b30 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
15b40 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
15b50 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
15b60 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
15b70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15b80 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
15b90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
15ba0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
15bb0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
15bc0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
15bd0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
15be0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
15bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15c00 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
15c10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
15c20 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
15c30 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
15c40 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
15c50 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
15c60 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
15c70 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
15c80 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
15c90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
15ca0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
15cb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
15cc0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15cd0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
15ce0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
15cf0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
15d00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15d10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15d20 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
15d30 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
15d40 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
15d50 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
15d60 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
15d70 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
15d80 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
15d90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
15da0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
15db0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
15dc0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
15dd0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
15de0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
15df0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
15e00 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
15e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
15e20 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15e30 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
15e40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
15e50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
15e60 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
15e70 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
15e80 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
15e90 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
15ea0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
15eb0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
15ec0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
15ed0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
15ee0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15ef0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
15f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15f10 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
15f20 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
15f30 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
15f40 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
15f50 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
15f60 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
15f70 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
15f80 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
15f90 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
15fa0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
15fb0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
15fc0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
15fd0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
15fe0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
15ff0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
16000 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
16010 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
16020 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
16030 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
16040 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
16050 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
16060 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
16070 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
16080 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
16090 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
160a0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
160b0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
160c0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
160d0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
160e0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
160f0 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
16100 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
16110 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
16120 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
16130 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
16140 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
16150 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
16160 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
16170 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
16180 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
16190 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
161a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
161b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
161c0 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
161d0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
161e0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
161f0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
16200 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
16210 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
16220 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
16230 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
16240 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
16250 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
16260 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
16270 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
16280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16290 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
162a0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
162b0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
162c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
162d0 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
162e0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
162f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
16300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16310 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
16320 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
16330 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
16340 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16350 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
16360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16370 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
16380 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
16390 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
163a0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
163b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
163c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
163d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
163e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
163f0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
16400 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
16410 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
16420 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
16430 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
16440 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
16450 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
16460 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
16470 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16480 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
16490 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
164a0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
164b0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
164c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
164d0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
164e0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
164f0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
16500 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
16510 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
16520 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
16530 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
16540 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
16550 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
16560 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
16570 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
16580 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
16590 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
165a0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
165b0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
165c0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
165d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
165e0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
165f0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
16600 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
16610 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
16620 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16630 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
16640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16650 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16660 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
16670 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
16680 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
16690 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
166a0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
166b0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
166c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
166d0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
166e0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
166f0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
16700 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
16710 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
16720 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
16730 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
16740 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
16750 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
16760 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
16770 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
16780 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
16790 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
167a0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
167b0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
167c0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
167d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
167e0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
167f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
16800 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
16810 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
16820 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
16830 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
16840 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
16850 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16860 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
16870 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
16880 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
16890 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
168a0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
168b0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
168c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
168d0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
168e0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
168f0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
16900 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
16910 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
16920 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
16930 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
16940 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
16950 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
16960 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
16970 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
16980 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
16990 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
169a0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
169b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
169c0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
169d0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
169e0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
169f0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
16a00 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
16a10 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
16a20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
16a30 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
16a40 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
16a50 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
16a60 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
16a70 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
16a80 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16a90 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
16aa0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
16ab0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
16ac0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
16ad0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
16ae0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
16af0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
16b00 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
16b10 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
16b20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
16b30 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
16b40 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
16b50 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
16b60 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
16b70 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
16b80 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
16b90 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
16ba0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
16bb0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
16bc0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
16bd0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
16be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
16bf0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
16c00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
16c10 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
16c20 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
16c30 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
16c40 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
16c50 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
16c60 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
16c70 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
16c80 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
16c90 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
16ca0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
16cb0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
16cc0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
16cd0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
16ce0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
16cf0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
16d00 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
16d10 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
16d20 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
16d30 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
16d40 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
16d50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
16d60 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
16d70 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
16d80 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
16d90 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
16da0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
16db0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
16dc0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
16dd0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
16de0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
16df0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
16e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
16e10 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
16e20 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
16e30 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
16e40 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
16e50 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
16e60 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
16e70 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
16e80 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
16e90 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
16ea0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
16eb0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
16ec0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
16ed0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
16ee0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
16ef0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
16f00 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
16f10 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
16f20 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
16f30 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
16f40 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
16f50 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
16f60 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
16f70 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
16f80 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
16f90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
16fa0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
16fb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
16fc0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
16fd0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
16fe0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
16ff0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
17000 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
17010 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
17020 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
17030 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
17040 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
17050 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
17060 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
17070 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
17080 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
17090 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
170a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
170b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
170c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
170d0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
170e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
170f0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
17100 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
17110 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
17120 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
17130 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
17140 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
17150 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
17160 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
17170 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
17180 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
17190 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
171a0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
171b0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
171c0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
171d0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
171e0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
171f0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
17200 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
17210 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
17220 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
17230 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
17240 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17250 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
17260 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
17270 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
17280 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
17290 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
172a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
172b0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
172c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
172d0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
172e0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
172f0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
17300 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
17310 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
17320 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
17330 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
17340 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
17350 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
17360 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
17370 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
17380 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
17390 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
173a0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
173b0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
173c0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
173d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
173e0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
173f0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
17400 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
17410 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
17420 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17430 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
17440 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
17450 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
17460 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
17470 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
17480 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
17490 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
174a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
174b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
174c0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
174d0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
174e0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
174f0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
17500 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
17510 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
17520 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
17530 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
17540 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
17550 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17560 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17570 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
17580 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
17590 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
175a0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
175b0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
175c0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
175d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
175e0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
175f0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
17600 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
17610 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
17620 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
17630 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
17640 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
17650 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
17660 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
17670 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17680 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
17690 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
176a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
176b0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
176c0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
176d0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
176e0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
176f0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
17700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17710 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
17720 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
17730 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
17740 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
17750 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
17760 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
17770 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
17780 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
17790 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
177a0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
177b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
177c0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
177d0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
177e0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
177f0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
17800 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
17810 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
17820 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
17830 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
17840 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
17850 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
17860 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
17870 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
17880 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
17890 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
178a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
178b0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
178c0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
178d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
178e0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
178f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
17900 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
17910 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
17920 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
17930 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
17940 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17950 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
17960 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
17970 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
17980 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
17990 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
179a0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
179b0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
179c0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
179d0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
179e0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
179f0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
17a00 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
17a10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17a20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
17a30 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
17a40 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
17a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17a60 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
17a70 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
17a80 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
17a90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17ab0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
17ac0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
17ad0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17ae0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17b00 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
17b10 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
17b20 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
17b30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17b50 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
17b60 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
17b70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17b80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17b90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
17ba0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
17bb0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
17bc0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
17bd0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
17be0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17bf0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
17c00 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
17c10 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
17c20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17c30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
17c40 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
17c50 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
17c60 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
17c70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17c80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
17c90 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
17ca0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
17cb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17cc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17cd0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
17ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
17cf0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17d00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17d10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17d20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
17d30 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
17d40 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
17d50 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
17d60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17d70 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
17d80 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
17d90 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17da0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17db0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17dc0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
17dd0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
17de0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
17df0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17e00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17e10 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
17e20 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
17e30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17e40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17e50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17e60 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
17e70 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
17e80 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
17e90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17ea0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17eb0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
17ec0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
17ed0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
17ee0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17ef0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17f00 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
17f10 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
17f20 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
17f30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17f50 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
17f60 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
17f70 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
17f80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
17fa0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
17fb0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
17fc0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17fd0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
17ff0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
18000 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
18010 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
18020 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
18030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
18040 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
18050 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
18060 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
18070 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18080 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
18090 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
180a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
180b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
180c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
180d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
180e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
180f0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
18100 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
18110 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18120 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
18130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18140 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
18150 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
18160 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
18170 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
18180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
18190 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
181a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
181b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
181c0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
181d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
181e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
181f0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
18200 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18210 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
18220 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
18230 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
18240 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
18250 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18260 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
18270 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
18280 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18290 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
182a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
182b0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
182c0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
182d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
182e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
182f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18300 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
18310 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
18320 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18330 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
18340 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18350 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
18360 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
18370 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18380 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
18390 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
183a0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
183b0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
183c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
183d0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
183e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
183f0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
18400 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
18410 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
18420 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
18430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18440 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
18450 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
18460 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
18470 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18480 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
18490 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
184a0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
184b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
184c0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
184d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
184e0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
184f0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
18500 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
18510 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
18520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18530 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
18540 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
18550 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
18560 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
18570 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
18580 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
18590 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
185a0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
185b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
185c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
185d0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
185e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
185f0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
18600 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
18610 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
18620 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
18630 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
18640 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
18650 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
18660 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
18670 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
18680 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
18690 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
186a0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
186b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
186c0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
186d0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
186e0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
186f0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
18700 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
18710 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
18720 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18730 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
18740 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18750 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
18760 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
18770 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
18780 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
18790 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
187a0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
187b0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
187c0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
187d0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
187e0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
187f0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
18800 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
18810 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
18820 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
18830 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
18840 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
18850 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
18860 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
18870 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
18880 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
18890 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
188a0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
188b0 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
188c0 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
188d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
188e0 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
188f0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
18900 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f  ^This routine co
18910 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
18920 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
18930 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
18940 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
18950 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
18960 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
18970 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
18980 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18990 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
189a0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
189b0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
189c0 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
189d0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
189e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
189f0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
18a00 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
18a10 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
18a20 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
18a30 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
18a40 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
18a50 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
18a60 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
18a70 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
18a80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
18a90 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
18aa0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
18ab0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
18ac0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
18ad0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
18ae0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f  dler must not do
18af0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
18b00 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
18b10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18b20 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
18b30 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
18b40 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
18b50 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
18b60 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
18b70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18b80 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
18b90 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
18ba0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
18bb0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
18bc0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
18bd0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
18be0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
18bf0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
18c00 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
18c10 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
18c20 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
18c30 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
18c40 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
18c50 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
18c60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
18c70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
18c80 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
18c90 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
18ca0 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
18cb0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
18cc0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
18cd0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
18ce0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
18cf0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
18d00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
18d10 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
18d20 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
18d30 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
18d40 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
18d50 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
18d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18d70 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
18d80 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
18d90 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
18da0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
18db0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
18dc0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
18dd0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
18de0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
18df0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
18e00 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
18e10 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
18e20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
18e30 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
18e40 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
18e50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
18e60 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
18e70 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
18e80 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
18e90 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
18ea0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
18eb0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
18ec0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
18ed0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
18ee0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
18ef0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
18f00 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
18f10 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
18f20 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
18f30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
18f40 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
18f50 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
18f60 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
18f70 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
18f80 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
18f90 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
18fa0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
18fb0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
18fc0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
18fd0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
18fe0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
18ff0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
19000 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
19010 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
19020 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
19030 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
19040 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
19050 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
19060 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
19070 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
19080 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
19090 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
190a0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
190b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
190c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
190d0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
190e0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
190f0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
19100 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
19110 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
19120 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
19130 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
19140 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19150 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
19160 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
19170 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
19180 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
19190 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
191a0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
191b0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
191c0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
191d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
191e0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
191f0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
19200 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
19210 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
19220 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
19230 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
19240 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
19250 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
19260 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
19270 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
19280 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
19290 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
192a0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
192b0 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  * and/or [SQLITE
192c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
192d0 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  HE] flags:)^.**.
192e0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
192f0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
19300 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
19310 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
19320 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
19330 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
19340 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
19350 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
19360 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
19370 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
19380 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
19390 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
193a0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
193b0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
193c0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
193d0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
193e0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
193f0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
19400 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
19410 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
19420 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
19430 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
19440 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
19450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
19460 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
19470 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
19480 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
19490 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
194a0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
194b0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
194c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
194d0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
194e0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
194f0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
19500 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
19510 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
19520 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
19530 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
19540 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
19550 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
19560 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
19570 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
19580 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
19590 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
195a0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
195b0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
195c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
195d0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
195e0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
195f0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
19600 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20  above or one of 
19610 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  the combinations
19620 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d   shown above com
19630 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  bined.** with th
19640 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
19650 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
19660 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
19670 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
19680 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61  N_SHAREDCACHE] a
19690 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
196a0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
196b0 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
196c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
196d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
196e0 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
196f0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
19700 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
19710 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19720 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
19730 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
19740 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
19750 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
19760 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
19770 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
19780 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
19790 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
197a0 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
197b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
197c0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
197d0 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
197e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
197f0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
19800 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
19810 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
19820 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
19830 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
19840 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
19850 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
19860 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
19870 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
19880 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
19890 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
198a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
198b0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
198c0 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
198d0 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
198e0 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
198f0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
19900 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
19910 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
19920 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
19930 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
19940 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
19950 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
19960 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
19970 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
19980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
19990 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
199a0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
199b0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
199c0 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
199d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
199e0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
199f0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
19a00 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
19a10 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
19a20 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
19a30 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
19a40 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
19a50 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
19a60 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
19a70 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
19a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
19a90 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
19aa0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
19ab0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
19ac0 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
19ad0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
19ae0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
19af0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
19b00 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
19b10 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
19b20 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
19b30 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
19b40 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
19b50 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
19b60 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
19b70 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
19b80 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
19b90 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
19ba0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
19bb0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
19bc0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
19bd0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
19be0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
19bf0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
19c00 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
19c10 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
19c20 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
19c30 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
19c40 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
19c50 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
19c60 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
19c70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19c80 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
19c90 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
19ca0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
19cb0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
19cc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
19cd0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
19ce0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
19cf0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
19d00 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
19d10 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
19d20 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
19d30 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
19d40 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
19d50 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
19d60 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
19d70 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
19d80 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
19d90 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
19da0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
19db0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
19dc0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
19dd0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
19de0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19df0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
19e00 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19e10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
19e20 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
19e30 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
19e40 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
19e50 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
19e60 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
19e70 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
19e80 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
19e90 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
19ea0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
19eb0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
19ec0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
19ed0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
19ee0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
19ef0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
19f00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
19f10 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
19f20 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
19f30 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
19f40 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
19f50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
19f60 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
19f70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
19f80 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
19f90 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
19fa0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
19fb0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
19fc0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
19fd0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
19fe0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
19ff0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1a000 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
1a010 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1a020 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1a030 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1a040 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1a050 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
1a060 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a070 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a080 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
1a090 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
1a0a0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
1a0b0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
1a0c0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
1a0d0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
1a0e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a0f0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
1a100 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
1a110 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a120 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1a130 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1a140 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1a150 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1a160 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1a170 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1a180 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1a190 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1a1a0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1a1b0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1a1c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1a1d0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1a1e0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1a1f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1a200 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1a210 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1a220 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1a230 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1a240 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
1a250 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1a260 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
1a270 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
1a280 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
1a290 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
1a2a0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
1a2b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1a2c0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
1a2d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1a2e0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
1a2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1a300 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1a310 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1a320 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1a330 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1a340 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1a350 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1a360 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1a370 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1a380 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
1a390 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1a3a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1a3b0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1a3c0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1a3d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1a3e0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1a3f0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1a400 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1a410 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1a420 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1a430 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1a440 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1a450 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1a460 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1a470 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1a480 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
1a490 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
1a4a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1a4b0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
1a4c0 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
1a4d0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
1a4e0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
1a4f0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
1a500 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
1a510 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
1a520 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
1a530 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
1a540 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
1a550 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
1a560 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
1a570 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
1a580 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
1a590 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
1a5a0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
1a5b0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
1a5c0 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
1a5d0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
1a5e0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
1a5f0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
1a600 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
1a610 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a620 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
1a630 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1a640 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
1a650 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1a660 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
1a670 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
1a680 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
1a690 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
1a6a0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
1a6b0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
1a6c0 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
1a6d0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
1a6e0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
1a6f0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
1a700 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1a710 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1a720 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1a730 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1a740 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1a750 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1a760 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1a770 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1a780 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1a790 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1a7a0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1a7b0 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
1a7c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1a7d0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
1a7e0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1a7f0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
1a800 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1a810 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1a820 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1a830 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1a840 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1a850 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a860 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1a870 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
1a880 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1a890 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1a8a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a8b0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1a8c0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1a8d0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1a8e0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1a8f0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1a900 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1a910 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1a920 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1a930 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1a940 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1a950 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1a960 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1a970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1a980 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1a990 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1a9a0 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1a9b0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1a9c0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1a9d0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1a9e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a9f0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1aa00 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1aa10 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1aa20 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1aa30 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1aa40 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1aa50 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1aa60 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1aa70 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1aa80 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1aa90 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1aaa0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1aab0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1aac0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1aad0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1aae0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1aaf0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1ab00 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1ab10 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1ab20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1ab30 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1ab40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1ab50 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1ab60 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1ab70 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1ab80 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1ab90 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1aba0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1abb0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1abc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1abd0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1abe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1abf0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1ac00 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
1ac10 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1ac20 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1ac30 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1ac40 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1ac50 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1ac60 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1ac70 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1ac80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1ac90 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1aca0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1acb0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1acc0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1acd0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1ace0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1acf0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1ad00 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1ad10 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1ad20 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1ad30 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1ad40 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1ad50 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1ad60 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1ad70 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1ad80 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1ad90 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1ada0 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  mit.)^.**.** ^If
1adb0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1adc0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1add0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1ade0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1adf0 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  ^(For the limit 
1ae00 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1ae10 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1ae20 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
1ae30 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
1ae40 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62   bound].** set b
1ae50 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
1ae60 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1ae70 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20  macro named .** 
1ae80 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1ae90 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54  _MAX_XYZ]..** (T
1aea0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1aeb0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1aec0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1aed0 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1aee0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1aef0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1af00 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1af10 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1af20 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1af30 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1af40 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
1af50 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
1af60 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
1af70 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
1af80 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
1af90 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
1afa0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
1afb0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
1afc0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
1afd0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
1afe0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
1aff0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
1b000 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
1b010 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
1b020 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
1b030 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
1b040 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
1b050 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
1b060 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
1b070 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
1b080 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
1b090 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
1b0a0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
1b0b0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
1b0c0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
1b0d0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
1b0e0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
1b0f0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
1b100 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
1b110 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1b120 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
1b130 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
1b140 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
1b150 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
1b160 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
1b170 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
1b180 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
1b190 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
1b1a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1b1b0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
1b1c0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
1b1d0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
1b1e0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
1b1f0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
1b200 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
1b210 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
1b220 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
1b230 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
1b240 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
1b250 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
1b260 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
1b270 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
1b280 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
1b290 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1b2a0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
1b2b0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
1b2c0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
1b2d0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
1b2e0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1b2f0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
1b300 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1b310 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1b320 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
1b330 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
1b340 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
1b350 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
1b360 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
1b370 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
1b380 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
1b390 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1b3a0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
1b3b0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
1b3c0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1b3d0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
1b3e0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
1b3f0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
1b400 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
1b410 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
1b420 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
1b430 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
1b440 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1b450 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
1b460 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b470 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
1b480 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
1b490 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
1b4a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b4b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1b4c0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1b4d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1b4e0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1b4f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1b500 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1b510 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1b520 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1b530 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b540 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1b550 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1b560 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1b570 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1b580 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1b590 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1b5a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1b5b0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1b5c0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1b5d0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1b5e0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1b5f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1b600 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1b610 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1b620 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1b630 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1b640 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1b650 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1b660 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1b670 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1b680 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1b690 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b6a0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1b6b0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1b6c0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1b6d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b6e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1b6f0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1b700 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b710 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1b720 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1b730 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1b740 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1b750 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1b760 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1b770 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1b780 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1b790 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
1b7a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b7b0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
1b7c0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
1b7d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1b7e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1b7f0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1b800 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1b810 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
1b820 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
1b830 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
1b840 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  d>.**.** ^(<dt>S
1b850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1b860 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1b870 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b880 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1b890 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1b8a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
1b8b0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
1b8c0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
1b8d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b8e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1b8f0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1b900 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b910 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1b920 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1b930 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1b940 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1b950 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1b960 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1b970 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1b980 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b990 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1b9a0 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
1b9b0 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
1b9c0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1b9d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1b9e0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1b9f0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1ba00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1ba10 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1ba20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1ba30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1ba40 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1ba50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1ba60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1ba70 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1ba80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1ba90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1baa0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1bab0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1bac0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1bad0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1bae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1baf0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1bb00 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1bb10 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1bb20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1bb30 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1bb40 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1bb50 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1bb60 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1bb70 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1bb80 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1bb90 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1bba0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1bbb0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1bbc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1bbd0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1bbe0 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1bbf0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1bc00 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1bc10 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
1bc20 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1bc30 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1bc40 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1bc50 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1bc60 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1bc70 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1bc80 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1bc90 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1bca0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1bcb0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1bcc0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1bcd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1bce0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1bcf0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1bd00 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1bd10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1bd20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1bd30 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
1bd40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1bd50 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
1bd60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
1bd70 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
1bd80 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1bd90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1bda0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1bdb0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1bdc0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1bdd0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1bde0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1bdf0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1be00 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1be10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1be20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1be30 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1be40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1be50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1be60 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1be70 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1be80 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
1be90 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1bea0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1beb0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1bec0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1bed0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1bee0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
1bef0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1bf00 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1bf10 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1bf20 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1bf30 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
1bf40 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1bf50 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1bf60 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1bf70 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1bf80 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1bf90 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1bfa0 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1bfb0 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1bfc0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1bfd0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1bfe0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1bff0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1c000 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1c010 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1c020 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1c030 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1c040 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1c050 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1c060 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1c070 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1c080 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1c090 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1c0a0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1c0b0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1c0c0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1c0d0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ytes..**.** ^If 
1c0e0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1c0f0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1c100 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1c110 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1c120 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1c130 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1c140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1c150 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1c160 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1c170 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1c180 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1c190 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1c1a0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1c1b0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1c1c0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1c1d0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
1c1e0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1c1f0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1c200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c210 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1c220 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1c230 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c240 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
1c250 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1c260 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1c270 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
1c280 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1c290 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1c2a0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1c2b0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1c2c0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1c2d0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1c2e0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
1c2f0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1c300 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1c310 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1c320 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1c330 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1c340 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1c350 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1c360 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1c370 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
1c380 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
1c390 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
1c3a0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
1c3b0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
1c3c0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
1c3d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
1c3e0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
1c3f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1c400 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c410 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1c420 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1c430 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1c440 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1c450 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1c460 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1c470 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1c480 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1c490 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1c4a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1c4b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1c4c0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1c4d0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
1c4e0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1c4f0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1c500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1c510 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1c520 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1c530 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1c540 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1c550 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1c560 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1c570 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1c580 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1c590 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1c5a0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
1c5b0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
1c5c0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1c5d0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
1c5e0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1c5f0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1c600 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1c610 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1c620 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1c630 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1c640 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1c650 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1c660 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1c670 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1c680 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1c690 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63 68 65  n.  ^If the sche
1c6a0 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1c6b0 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1c6c0 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1c6d0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1c6e0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1c6f0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1c700 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1c710 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1c720 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1c730 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1c740 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1c750 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1c760 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1c770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c780 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1c790 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1c7a0 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1c7b0 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1c7c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1c7d0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1c7e0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1c7f0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1c800 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1c810 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1c820 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1c830 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
1c840 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1c850 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c860 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1c870 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1c880 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1c890 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1c8a0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
1c8b0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1c8c0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1c8d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c8e0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1c8f0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1c900 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1c910 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
1c920 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
1c930 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1c940 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1c950 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1c960 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
1c970 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1c980 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1c990 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1c9a0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1c9b0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1c9c0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1c9d0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1c9e0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1c9f0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1ca00 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1ca10 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  i>.** ^If the va
1ca20 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65  lue of a [parame
1ca30 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
1ca40 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45  eter] in the WHE
1ca50 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a  RE clause might.
1ca60 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 71 75  ** change the qu
1ca70 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
1ca80 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74  tatement, then t
1ca90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79  he statement may
1caa0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1cab0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20  ally recompiled 
1cac0 28 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64  (as if there had
1cad0 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63   been a schema c
1cae0 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69  hange) on the fi
1caf0 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rst .** [sqlite3
1cb00 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
1cb10 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
1cb20 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73  ge to the .** [s
1cb30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1cb40 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
1cb50 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  the [parameter].
1cb60 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
1cb70 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
1cb80 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1cb90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1cba0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1cbb0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1cbc0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1cbd0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1cbe0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1cbf0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1cc00 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1cc10 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1cc20 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1cc30 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1cc40 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1cc50 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1cc60 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1cc70 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1cc80 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1cc90 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1cca0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1ccb0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1ccc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ccd0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1cce0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1ccf0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1cd00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1cd10 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1cd20 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1cd30 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1cd40 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1cd50 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1cd60 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1cd70 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1cd80 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1cd90 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1cda0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1cdb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1cdc0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1cdd0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1cde0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1cdf0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1ce00 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1ce10 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1ce20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1ce30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1ce40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1ce50 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1ce60 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1ce70 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1ce80 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1ce90 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1cea0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1ceb0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1cec0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ced0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1cee0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1cef0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1cf00 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1cf10 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1cf20 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1cf30 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1cf40 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1cf50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1cf60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1cf70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1cf80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1cf90 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1cfa0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1cfb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1cfc0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1cfd0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1cfe0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1cff0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1d000 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1d010 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1d020 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1d030 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1d040 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1d050 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1d060 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1d070 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1d080 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1d090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d0a0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1d0b0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
1d0c0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1d0d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1d0e0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
1d0f0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
1d100 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
1d110 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
1d120 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d130 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
1d140 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
1d150 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1d160 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1d170 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1d180 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d190 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
1d1a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1d1b0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
1d1c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1d1d0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
1d1e0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1d1f0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
1d200 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
1d210 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1d220 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
1d230 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
1d240 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
1d250 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1d260 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
1d270 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
1d280 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
1d290 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
1d2a0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
1d2b0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
1d2c0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
1d2d0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
1d2e0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
1d2f0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
1d300 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
1d310 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
1d320 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1d330 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1d340 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1d350 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1d360 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1d370 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1d380 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1d390 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1d3a0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1d3b0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1d3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1d3d0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1d3e0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1d3f0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1d400 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1d410 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1d420 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1d430 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1d440 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1d450 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1d460 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
1d470 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
1d480 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
1d490 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1d4a0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
1d4b0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
1d4c0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
1d4d0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
1d4e0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
1d4f0 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
1d500 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
1d510 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
1d520 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d530 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
1d540 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
1d550 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
1d560 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d570 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
1d580 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1d590 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
1d5a0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
1d5b0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
1d5c0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
1d5d0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
1d5e0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
1d5f0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
1d600 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
1d610 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
1d620 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
1d630 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
1d640 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
1d650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1d660 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
1d670 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
1d680 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1d690 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1d6a0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1d6b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1d6c0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
1d6d0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
1d6e0 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
1d6f0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
1d700 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
1d710 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
1d720 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
1d730 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
1d740 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
1d750 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1d760 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1d770 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1d780 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1d790 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
1d7a0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
1d7b0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
1d7c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1d7d0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
1d7e0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
1d7f0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
1d800 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
1d810 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
1d820 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1d830 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
1d840 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
1d850 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1d860 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1d870 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1d880 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1d890 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1d8a0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1d8b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1d8c0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1d8d0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1d8e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1d8f0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1d900 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1d910 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
1d920 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
1d930 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1d940 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
1d950 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
1d960 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1d970 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1d980 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1d990 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1d9a0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1d9b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1d9c0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
1d9d0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
1d9e0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1d9f0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1da00 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1da10 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1da20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1da30 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
1da40 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1da50 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1da60 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1da70 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1da80 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1da90 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1daa0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1dab0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1dac0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1dad0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1dae0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1daf0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1db00 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1db10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1db20 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1db30 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1db40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1db50 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1db60 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1db70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1db80 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1db90 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1dba0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1dbb0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1dbc0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1dbd0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1dbe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1dbf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1dc00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dc10 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1dc20 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1dc30 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
1dc40 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1dc50 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1dc60 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1dc70 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1dc80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1dc90 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1dca0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1dcb0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1dcc0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
1dcd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1dce0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
1dcf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1dd00 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1dd10 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1dd20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1dd30 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1dd40 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
1dd50 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
1dd60 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
1dd70 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1dd80 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
1dd90 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
1dda0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
1ddb0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
1ddc0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
1ddd0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
1dde0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
1ddf0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1de00 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1de10 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
1de20 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
1de30 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  ifer.)^  ^The va
1de40 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
1de50 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1de60 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1de70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
1de80 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
1de90 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
1dea0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
1deb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1dec0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
1ded0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
1dee0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1def0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
1df00 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1df10 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
1df20 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1df30 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1df40 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
1df50 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
1df60 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1df70 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
1df80 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
1df90 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
1dfa0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
1dfb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
1dfc0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
1dfd0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1dfe0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1dff0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
1e000 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1e010 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1e020 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
1e030 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
1e040 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
1e050 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
1e060 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
1e070 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1e080 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
1e090 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
1e0a0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
1e0b0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
1e0c0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
1e0d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e0e0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
1e0f0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
1e100 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1e110 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1e120 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1e130 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
1e140 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
1e150 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
1e160 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1e170 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
1e180 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1e190 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
1e1a0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1e1b0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
1e1c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1e1d0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1e1e0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1e1f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
1e200 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
1e210 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1e220 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1e230 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1e240 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1e250 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1e260 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1e270 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1e280 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
1e290 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
1e2a0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1e2b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1e2c0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
1e2d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1e2e0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
1e2f0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
1e300 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
1e310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1e320 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
1e330 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1e340 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
1e350 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1e360 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
1e370 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
1e380 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
1e390 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
1e3a0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
1e3b0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
1e3c0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
1e3d0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
1e3e0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
1e3f0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1e400 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69  h it. ^If the fi
1e410 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1e420 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1e430 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1e440 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1e450 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1e460 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1e470 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1e480 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1e490 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1e4a0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1e4b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
1e4c0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1e4d0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1e4e0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1e4f0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1e500 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1e510 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1e520 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1e530 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1e540 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e550 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1e560 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e570 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
1e580 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
1e590 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
1e5a0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
1e5b0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
1e5c0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
1e5d0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
1e5e0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
1e5f0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
1e600 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
1e610 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
1e620 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
1e630 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
1e640 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
1e650 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
1e660 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
1e670 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
1e680 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
1e690 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e6a0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
1e6b0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
1e6c0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
1e6d0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
1e6e0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
1e6f0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
1e700 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
1e710 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
1e720 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
1e730 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1e740 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
1e750 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1e760 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
1e770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1e780 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
1e790 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
1e7a0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
1e7b0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
1e7c0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
1e7d0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
1e7e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
1e7f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
1e800 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1e810 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
1e820 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
1e830 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
1e840 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
1e850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e860 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
1e870 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
1e880 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
1e890 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
1e8a0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1e8b0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
1e8c0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
1e8d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
1e8e0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
1e8f0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
1e900 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1e910 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1e920 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e930 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
1e940 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1e950 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1e960 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
1e970 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
1e980 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
1e990 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
1e9a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
1e9b0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1e9c0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
1e9d0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
1e9e0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
1e9f0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
1ea00 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
1ea10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1ea20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1ea30 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1ea40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ea50 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1ea60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ea70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1ea80 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1ea90 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
1eaa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1eab0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1eac0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1ead0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1eae0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
1eaf0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1eb00 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
1eb10 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
1eb20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1eb30 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
1eb40 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
1eb50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1eb60 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
1eb70 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
1eb80 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
1eb90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
1eba0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ebb0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
1ebc0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
1ebd0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
1ebe0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1ebf0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1ec00 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
1ec10 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1ec20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1ec30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1ec40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
1ec50 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
1ec60 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
1ec70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1ec80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ec90 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1eca0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1ecb0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1ecc0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1ecd0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
1ece0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1ecf0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
1ed00 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1ed10 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
1ed20 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
1ed30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ed40 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
1ed50 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
1ed60 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
1ed70 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
1ed80 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
1ed90 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
1eda0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
1edb0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1edc0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1edd0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1ede0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1edf0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1ee00 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
1ee10 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
1ee20 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
1ee30 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1ee40 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
1ee50 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
1ee60 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
1ee70 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
1ee80 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
1ee90 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
1eea0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
1eeb0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
1eec0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
1eed0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
1eee0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
1eef0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
1ef00 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
1ef10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1ef20 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1ef30 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1ef40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ef50 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1ef60 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1ef70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1ef80 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1ef90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1efa0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1efb0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1efc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1efd0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1efe0 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
1eff0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1f000 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
1f010 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1f020 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
1f030 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
1f040 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1f050 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1f060 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
1f070 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1f080 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1f090 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1f0a0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1f0b0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1f0c0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1f0d0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1f0e0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1f0f0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1f100 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1f110 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1f120 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1f130 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1f140 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1f150 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1f160 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
1f170 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1f180 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1f190 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1f1a0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
1f1b0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
1f1c0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
1f1d0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
1f1e0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1f1f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1f200 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1f210 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1f220 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
1f230 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
1f240 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1f250 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
1f260 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1f270 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1f280 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1f290 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
1f2a0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
1f2b0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
1f2c0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
1f2d0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
1f2e0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
1f2f0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
1f300 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
1f310 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
1f320 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1f330 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1f340 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f350 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f360 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1f370 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1f380 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1f390 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1f3a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f3b0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1f3c0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f3d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f3e0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
1f3f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1f400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f410 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
1f420 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
1f430 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
1f440 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1f450 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1f460 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1f470 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
1f480 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1f490 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1f4a0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1f4b0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1f4c0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1f4d0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1f4e0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
1f4f0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
1f500 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
1f510 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
1f520 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
1f530 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1f540 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1f550 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1f560 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f570 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1f580 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1f590 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1f5a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f5b0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1f5c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1f5d0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1f5e0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1f5f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f600 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1f610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f620 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1f630 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1f640 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f650 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1f660 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1f670 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1f680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1f690 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1f6a0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1f6b0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
1f6c0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
1f6d0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
1f6e0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
1f6f0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
1f700 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
1f710 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1f720 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
1f730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f740 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
1f750 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
1f760 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1f770 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1f780 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
1f790 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
1f7a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1f7b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f7c0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
1f7d0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
1f7e0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
1f7f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1f800 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1f810 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
1f820 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
1f830 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
1f840 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1f850 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
1f860 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
1f870 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
1f880 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
1f890 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
1f8a0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69   [UPDATE])..*/.i
1f8b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1f8c0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1f8d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1f8e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1f8f0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1f900 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
1f910 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1f920 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
1f930 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
1f940 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
1f950 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
1f960 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1f970 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
1f980 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1f990 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
1f9a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f9b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1f9c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f9d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
1f9e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
1f9f0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
1fa00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1fa10 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1fa20 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1fa30 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
1fa40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fa50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1fa60 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1fa70 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1fa80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1fa90 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1faa0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1fab0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
1fac0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
1fad0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
1fae0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
1faf0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
1fb00 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
1fb10 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
1fb20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fb30 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
1fb40 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
1fb50 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1fb60 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1fb70 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
1fb80 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1fb90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1fba0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
1fbb0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
1fbc0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
1fbd0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1fbe0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1fbf0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1fc00 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1fc10 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1fc20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
1fc30 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
1fc40 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
1fc50 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1fc60 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1fc70 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1fc80 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1fc90 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1fca0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1fcb0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1fcc0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1fcd0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1fce0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1fcf0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1fd00 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1fd10 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1fd20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1fd30 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1fd40 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1fd50 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
1fd60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1fd70 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1fd80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1fd90 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1fda0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1fdb0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1fdc0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1fdd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1fde0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1fdf0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
1fe00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1fe10 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
1fe20 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
1fe30 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
1fe40 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
1fe50 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1fe60 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
1fe70 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
1fe80 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
1fe90 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
1fea0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
1feb0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1fec0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1fed0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1fee0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1fef0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1ff00 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
1ff10 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
1ff20 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
1ff30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
1ff40 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
1ff50 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1ff60 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
1ff70 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
1ff80 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
1ff90 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
1ffa0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
1ffb0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
1ffc0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
1ffd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ffe0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
1fff0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
20000 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
20010 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
20020 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
20030 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
20040 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
20050 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
20060 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
20070 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
20080 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
20090 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
200a0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
200b0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
200c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
200d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
200e0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
200f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
20100 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
20110 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
20120 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
20130 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
20140 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
20150 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
20160 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
20170 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
20180 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
20190 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
201a0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
201b0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
201c0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
201d0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
201e0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
201f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
20200 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
20210 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
20220 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
20230 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
20240 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
20250 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
20260 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
20270 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
20280 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
20290 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
202a0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
202b0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
202c0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
202d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
202e0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
202f0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
20300 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
20310 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
20320 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
20330 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
20340 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
20350 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
20360 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
20370 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
20380 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
20390 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
203a0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
203b0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
203c0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
203d0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
203e0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
203f0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
20400 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
20410 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
20420 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
20430 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
20440 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
20450 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
20460 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
20470 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
20480 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
20490 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
204a0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
204b0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
204c0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
204d0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
204e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
204f0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
20500 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
20510 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
20520 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
20530 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
20540 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
20550 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
20560 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
20570 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
20580 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
20590 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
205a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
205b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
205c0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
205d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
205e0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
205f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20600 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20620 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
20630 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20640 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20650 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
20660 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
20670 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
20680 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
20690 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
206a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
206b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
206c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
206d0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
206e0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
206f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
20710 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
20720 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
20730 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
20740 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
20750 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
20760 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
20770 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
20780 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20790 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
207a0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
207b0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
207c0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
207d0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
207e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
207f0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
20800 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
20810 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
20820 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
20830 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
20840 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
20850 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
20860 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
20870 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
20880 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
20890 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
208a0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
208b0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
208c0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
208d0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
208e0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
208f0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
20900 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
20910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
20920 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
20930 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
20940 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
20950 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
20960 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
20970 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
20980 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
20990 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
209a0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
209b0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
209c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
209d0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
209e0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
209f0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
20a00 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
20a10 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
20a20 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
20a30 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
20a40 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
20a50 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
20a60 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
20a70 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
20a80 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
20a90 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
20aa0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
20ab0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
20ac0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
20ad0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
20ae0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
20af0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
20b00 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
20b10 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
20b20 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
20b30 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
20b40 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
20b50 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
20b60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
20b70 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
20b80 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
20b90 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
20ba0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
20bb0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
20bc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
20bd0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
20be0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20bf0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
20c00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20c10 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
20c20 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
20c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20c40 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
20c50 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
20c60 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
20c70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
20c80 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
20c90 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
20ca0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20cb0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
20cc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20cd0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
20ce0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
20cf0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
20d00 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
20d10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
20d20 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
20d30 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
20d40 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
20d50 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
20d60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
20d70 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
20d80 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
20d90 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
20da0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
20db0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
20dc0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
20dd0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
20de0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
20df0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
20e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20e10 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
20e20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20e30 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
20e40 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
20e50 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
20e60 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
20e70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20e80 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
20e90 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
20ea0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
20eb0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
20ec0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
20ed0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
20ee0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
20ef0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
20f00 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
20f10 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
20f20 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
20f30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
20f40 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
20f50 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
20f60 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
20f70 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
20f80 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
20f90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
20fa0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
20fb0 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
20fc0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
20fd0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
20fe0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
20ff0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
21000 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
21010 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
21020 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
21030 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
21040 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
21050 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
21060 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
21070 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
21080 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
21090 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
210a0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
210b0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
210c0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
210d0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
210e0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
210f0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
21100 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
21110 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
21120 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
21130 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
21140 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
21150 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
21160 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
21170 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
21180 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
21190 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
211a0 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
211b0 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
211c0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
211d0 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
211e0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
211f0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
21200 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
21210 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
21220 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
21230 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
21240 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
21250 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
21260 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
21270 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
21280 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
21290 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
212a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
212b0 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
212c0 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
212d0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
212e0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
212f0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
21300 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
21310 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
21320 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
21330 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
21340 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
21350 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
21360 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
21370 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
21380 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
21390 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
213a0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
213b0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
213c0 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
213d0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
213e0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
213f0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
21400 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
21410 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
21420 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
21430 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
21440 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
21450 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
21460 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
21470 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
21480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
21490 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
214a0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
214b0 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
214c0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
214d0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
214e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
214f0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
21500 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
21510 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
21520 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
21530 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
21540 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
21550 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
21560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21570 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
21580 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
21590 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
215a0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
215b0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
215c0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
215d0 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
215e0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
215f0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
21600 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
21610 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
21620 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
21630 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
21640 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21650 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
21660 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
21670 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21680 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
21690 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
216a0 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
216b0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
216c0 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
216d0 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
216e0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
216f0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
21700 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
21710 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
21720 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
21730 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
21740 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
21750 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
21760 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
21770 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
21780 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
21790 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
217a0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
217b0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
217c0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
217d0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
217e0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
217f0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
21800 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
21810 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
21820 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
21830 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
21840 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21850 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
21860 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
21870 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
21880 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
21890 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
218a0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
218b0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
218c0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
218d0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
218e0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
218f0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
21900 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
21910 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
21920 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
21930 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
21940 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
21950 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
21960 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21970 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21980 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
21990 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
219a0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
219b0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
219c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
219d0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
219e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
219f0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
21a00 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
21a10 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
21a20 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
21a30 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
21a40 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
21a50 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
21a60 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
21a70 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
21a80 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
21a90 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
21aa0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
21ab0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
21ac0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
21ad0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65  ata_count(P) the
21ae0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
21af0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20  ns in the.** of 
21b00 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
21b10 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
21b20 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74  ement] P..*/.int
21b30 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
21b40 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21b50 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
21b60 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
21b70 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
21b80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
21b90 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
21ba0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
21bb0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
21bc0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
21bd0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
21be0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
21bf0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
21c00 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
21c10 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
21c20 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
21c30 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
21c40 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
21c50 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
21c60 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
21c70 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
21c80 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
21c90 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
21ca0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
21cb0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
21cc0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
21cd0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
21ce0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
21cf0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
21d00 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
21d10 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
21d20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
21d30 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
21d40 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
21d50 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
21d60 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
21d70 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
21d80 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
21d90 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
21da0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
21db0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
21dc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
21dd0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
21de0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
21df0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
21e00 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
21e10 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
21e20 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
21e30 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
21e40 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
21e50 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
21e60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
21e70 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
21e80 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
21e90 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
21ea0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
21eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
21ec0 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
21ed0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
21ee0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
21ef0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
21f00 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
21f10 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
21f20 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
21f30 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
21f40 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
21f50 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
21f60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
21f70 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
21f80 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
21f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
21fa0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
21fb0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
21fc0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
21fd0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
21fe0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
21ff0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
22000 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
22010 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
22020 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
22030 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
22040 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
22050 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
22060 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
22070 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
22080 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
22090 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
220a0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
220b0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
220c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
220d0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
220e0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
220f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
22100 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
22110 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
22120 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
22130 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
22140 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
22150 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
22160 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
22170 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
22180 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
22190 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
221a0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
221b0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
221c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
221d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
221e0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
221f0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
22200 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
22210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
22220 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
22230 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
22240 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
22250 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
22260 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
22270 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
22280 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
22290 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
222a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
222b0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
222c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
222d0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
222e0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
222f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
22300 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
22310 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
22320 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
22330 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
22340 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
22350 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22360 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
22370 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
22380 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
22390 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
223a0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
223b0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
223c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
223d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
223e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
223f0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
22400 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
22410 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
22420 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
22430 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
22440 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
22450 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
22460 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
22470 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
22480 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
22490 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
224a0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
224b0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
224c0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
224d0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
224e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
224f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
22500 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
22510 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
22520 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
22530 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
22540 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
22550 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
22560 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
22570 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
22580 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
22590 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
225a0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
225b0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
225c0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
225d0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
225e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
225f0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
22600 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
22610 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
22620 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
22630 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
22640 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
22650 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22660 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
22670 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
22680 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
22690 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
226a0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
226b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
226c0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
226d0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
226e0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
226f0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
22700 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
22710 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
22720 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
22730 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
22740 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
22750 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
22760 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
22770 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
22780 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
22790 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
227a0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
227b0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
227c0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
227d0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
227e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65   string..** ^The
227f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
22800 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
22810 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
22820 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
22830 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
22840 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
22850 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
22860 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
22870 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
22880 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
22890 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
228a0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
228b0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
228c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
228d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
228e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
228f0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
22900 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
22910 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
22920 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
22930 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
22940 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
22950 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
22960 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
22970 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72  LOB is an arbitr
22980 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
22990 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
229a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
229b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
229c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
229d0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
229e0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
229f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
22a00 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
22a10 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
22a20 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
22a30 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
22a40 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65  f UTF-8..** ^The
22a50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
22a60 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
22a70 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
22a80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
22a90 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
22aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
22ab0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
22ac0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
22ad0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
22ae0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
22af0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22b00 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
22b10 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
22b20 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
22b30 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
22b40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
22b50 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
22b60 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
22b70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
22b80 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
22b90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
22ba0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
22bb0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
22bc0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
22bd0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
22be0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
22bf0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
22c00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
22c10 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
22c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
22c30 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
22c40 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
22c50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
22c60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
22c70 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
22c80 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
22c90 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
22ca0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
22cb0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
22cc0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
22cd0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
22ce0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
22cf0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
22d00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
22d10 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
22d20 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
22d30 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
22d40 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
22d50 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
22d60 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
22d70 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
22d80 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
22d90 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
22da0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
22db0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
22dc0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
22dd0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
22de0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
22df0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
22e00 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
22e10 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
22e20 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
22e30 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
22e40 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
22e50 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
22e60 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
22e70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
22e80 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
22e90 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
22ea0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
22eb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
22ec0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
22ed0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
22ee0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
22ef0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
22f00 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
22f10 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
22f20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
22f30 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
22f40 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
22f50 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
22f60 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
22f70 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
22f80 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
22f90 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
22fa0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
22fb0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
22fc0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
22fd0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
22fe0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
22ff0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
23000 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
23010 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
23020 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
23030 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
23040 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
23050 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
23060 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
23070 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
23080 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
23090 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
230a0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
230b0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
230c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
230d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
230e0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
230f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
23100 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
23110 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
23120 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
23130 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
23140 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
23150 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
23160 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
23170 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
23180 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
23190 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
231a0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
231b0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
231c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
231d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
231e0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
231f0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
23200 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
23210 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
23220 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
23230 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
23240 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
23250 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
23260 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
23270 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
23280 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
23290 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
232a0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
232b0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
232c0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
232d0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
232e0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
232f0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
23300 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
23310 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
23320 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
23330 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
23340 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
23350 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
23360 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
23370 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
23380 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
23390 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
233a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
233b0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
233c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
233d0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
233e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
233f0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
23400 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79  lidated..** ^(Ty
23410 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
23420 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
23430 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
23440 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
23450 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
23460 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
23470 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
23480 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
23490 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
234a0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
234b0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
234c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
234d0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
234e0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
234f0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
23500 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
23510 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
23520 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
23530 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
23540 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
23550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23560 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
23570 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23580 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
23590 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
235a0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
235b0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
235c0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
235d0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
235e0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
235f0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
23600 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23610 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
23620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23630 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
23640 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
23650 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
23660 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
23670 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  i>.** </ul>)^.**
23680 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
23690 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
236a0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
236b0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
236c0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
236d0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
236e0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
236f0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
23700 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
23710 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
23720 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
23730 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
23740 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
23750 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
23760 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
23770 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
23780 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
23790 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
237a0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
237b0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
237c0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
237d0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
237e0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
237f0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  lidated..**.** ^
23800 28 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20  (The safest and 
23810 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
23820 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
23830 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
23840 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
23850 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23860 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
23870 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
23880 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
23890 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
238a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
238b0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
238c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
238d0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
238e0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
238f0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
23900 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
23910 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
23920 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
23930 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
23940 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
23950 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  >)^.**.** In oth
23960 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
23970 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
23980 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
23990 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
239a0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
239b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
239c0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
239d0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
239e0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
239f0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
23a00 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
23a10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
23a20 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
23a30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
23a40 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
23a50 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
23a60 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
23a70 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
23a80 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
23a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23aa0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
23ab0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
23ac0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
23ad0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
23ae0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23af0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
23b00 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
23b10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23b20 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
23b30 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
23b40 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
23b50 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
23b60 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
23b70 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
23b80 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
23b90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23ba0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
23bb0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
23bc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23bd0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
23be0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
23bf0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
23c00 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
23c10 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
23c20 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
23c30 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
23c40 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
23c50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
23c60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
23c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23c80 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
23c90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
23ca0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
23cb0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
23cc0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
23cd0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
23ce0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
23cf0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
23d00 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
23d10 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
23d20 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
23d30 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
23d40 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
23d50 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
23d60 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
23d70 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
23d80 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
23d90 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
23da0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
23db0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
23dc0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
23dd0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
23de0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
23df0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
23e00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
23e10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23e20 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
23e30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
23e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
23e50 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
23e60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23e70 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
23e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
23e90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
23ea0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
23eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
23ec0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
23ed0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
23ee0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
23ef0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
23f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23f10 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
23f20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
23f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23f40 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
23f50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
23f60 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23f70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
23f80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23f90 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
23fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23fb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23fc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
23fd0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
23fe0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
23ff0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24000 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
24010 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
24020 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
24030 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
24040 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24050 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
24060 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
24070 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
24080 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24090 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74  .** ^If the stat
240a0 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
240b0 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
240c0 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
240d0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
240e0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
240f0 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75  urned. ^If execu
24100 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
24110 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
24120 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  n an.** [error c
24130 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
24140 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
24150 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24160 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
24170 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
24180 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
24190 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
241a0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
241b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
241c0 5e 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20  ^If the virtual 
241d0 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a  machine has not.
241e0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
241f0 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
24200 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
24210 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
24220 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
24230 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
24240 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
24250 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e  pt | interrupt].
24260 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20  .** ^Incomplete 
24270 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
24280 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
24290 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
242a0 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
242b0 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
242c0 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
242d0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
242e0 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
242f0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
24300 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24310 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
24320 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
24330 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24340 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
24350 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
24360 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
24370 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
24380 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
24390 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
243a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
243b0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
243c0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
243d0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
243e0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
243f0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
24400 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
24410 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
24420 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
24430 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
24440 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
24450 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
24460 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
24470 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
24480 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
24490 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
244a0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
244b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
244c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
244d0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
244e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
244f0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
24500 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
24510 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
24520 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
24530 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
24540 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24550 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
24560 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24570 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
24580 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
24590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
245a0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
245b0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
245c0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
245d0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
245e0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
245f0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
24600 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
24610 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
24620 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
24630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
24640 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
24650 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24660 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
24670 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
24680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
24690 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
246a0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
246b0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
246c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
246d0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
246e0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
246f0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
24700 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
24710 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
24720 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
24730 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24740 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
24750 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
24760 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24780 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
24790 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
247a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
247b0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
247c0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
247d0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
247e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
247f0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
24800 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
24810 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
24820 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
24830 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e  * ^These two fun
24840 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
24850 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
24860 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
24870 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
24880 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
24890 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
248a0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
248b0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
248c0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
248d0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
248e0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
248f0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
24900 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20  ference between 
24910 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68  the.** two is th
24920 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  at the second pa
24930 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d  rameter, the nam
24940 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
24950 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  ) function or.**
24960 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65   aggregate, is e
24970 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20  ncoded in UTF-8 
24980 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
24990 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
249a0 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20  d UTF-16.** for 
249b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
249c0 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  unction16()..**.
249d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
249e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
249f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24a00 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
24a10 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
24a20 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
24a30 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
24a40 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
24a50 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
24a60 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
24a70 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
24a80 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
24a90 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
24aa0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
24ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24ac0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
24ad0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
24ae0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24af0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
24b00 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
24b10 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
24b20 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
24b30 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
24b40 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
24b50 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
24b60 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
24b70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
24b80 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
24b90 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
24ba0 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
24bb0 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
24bc0 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  .  ^Any attempt 
24bd0 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
24be0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
24bf0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
24c00 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
24c10 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
24c20 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
24c30 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24c40 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
24c50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
24c60 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
24c70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
24c80 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
24c90 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
24ca0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
24cb0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
24cc0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
24cd0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
24ce0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
24cf0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
24d00 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
24d10 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
24d20 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
24d30 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24d40 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
24d50 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
24d60 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
24d70 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
24d80 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
24d90 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
24da0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
24db0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
24dc0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
24dd0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
24de0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
24df0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
24e00 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
24e10 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
24e20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
24e30 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
24e40 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24e50 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
24e60 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
24e70 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
24e80 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
24e90 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
24ea0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
24eb0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
24ec0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
24ed0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
24ee0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
24ef0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
24f00 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
24f10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
24f20 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
24f30 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
24f40 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
24f50 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
24f60 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
24f70 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
24f80 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
24f90 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
24fa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
24fb0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
24fc0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
24fd0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
24fe0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
24ff0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
25000 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
25010 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
25020 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
25030 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
25040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
25050 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
25060 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
25070 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
25080 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
25090 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
250a0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
250b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
250c0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
250d0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
250e0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
250f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
25100 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
25110 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
25120 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
25130 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
25140 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
25150 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c  .** The seventh,
25160 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
25170 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
25180 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
25190 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
251a0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
251b0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
251c0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
251d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
251e0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
251f0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
25200 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
25210 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
25220 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
25230 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
25240 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
25250 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
25260 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
25270 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
25280 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
25290 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
252a0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
252b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
252c0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
252d0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
252e0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
252f0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
25300 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
25310 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
25320 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
25330 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
25340 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63  three function c
25350 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
25360 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
25370 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
25380 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
25390 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
253a0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
253b0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
253c0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
253d0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
253e0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
253f0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
25400 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
25410 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
25420 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
25430 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
25440 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
25450 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
25460 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
25470 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
25480 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
25490 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
254a0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
254b0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
254c0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
254d0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
254e0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
254f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
25500 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
25510 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
25520 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
25530 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
25540 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
25550 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
25560 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
25570 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
25580 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
25590 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
255a0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
255b0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
255c0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
255d0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
255e0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
255f0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
25600 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
25610 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
25620 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
25630 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
25640 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
25650 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
25660 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
25670 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
25680 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
25690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
256a0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
256b0 20 5e 54 68 65 20 66 69 72 73 74 20 61 70 70 6c   ^The first appl
256c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
256d0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
256e0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
256f0 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
25700 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
25710 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
25720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25730 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
25740 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 71 75  ame..** ^Subsequ
25750 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ent application-
25760 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25770 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61  s of the same na
25780 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65  me only override
25790 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69   .** prior appli
257a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
257b0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72  unctions that ar
257c0 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68  e an exact match
257d0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62   for the.** numb
257e0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
257f0 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65   and preferred e
25800 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
25810 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
25820 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
25830 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
25840 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
25850 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
25860 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
25870 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
25880 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
25890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
258a0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
258b0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
258c0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
258d0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
258e0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
258f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25900 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25910 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25920 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25930 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
25940 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
25950 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
25960 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
25970 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
25980 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
25990 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
259a0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
259b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
259c0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
259d0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
259e0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
259f0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
25a00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25a10 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
25a20 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
25a30 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
25a40 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
25a50 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
25a60 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
25a70 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
25a80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25a90 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
25aa0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
25ab0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
25ac0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
25ad0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
25ae0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
25af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
25b00 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
25b10 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
25b20 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
25b30 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
25b40 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
25b50 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
25b60 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
25b70 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
25b80 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
25b90 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
25ba0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
25bb0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
25bc0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
25bd0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
25be0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
25bf0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
25c00 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
25c10 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
25c20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
25c30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25c40 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
25c50 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
25c60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25c70 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
25c80 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
25c90 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
25ca0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
25cb0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
25cc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25cd0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
25ce0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
25cf0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
25d00 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
25d10 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
25d20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
25d30 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
25d40 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
25d50 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
25d60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
25d70 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
25d80 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
25d90 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
25da0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
25db0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
25dc0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
25dd0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
25de0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
25df0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
25e00 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
25e10 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
25e20 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
25e30 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
25e40 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
25e50 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
25e60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
25e70 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
25e80 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
25e90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
25ea0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
25eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
25ec0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
25ed0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
25ee0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
25ef0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
25f00 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
25f10 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
25f20 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
25f30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
25f40 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
25f50 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
25f60 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
25f70 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
25f80 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
25f90 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
25fa0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
25fb0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
25fc0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
25fd0 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
25fe0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
25ff0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
26000 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
26010 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
26020 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
26030 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
26040 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
26050 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
26060 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
26070 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
26080 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
26090 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
260a0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
260b0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
260c0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
260d0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
260e0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
260f0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
26100 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
26110 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
26120 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
26130 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26140 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
26150 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26160 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
26170 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
26180 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
26190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
261a0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
261b0 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
261c0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
261d0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
261e0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
261f0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
26200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26210 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
26220 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
26230 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
26240 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
26250 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
26260 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
26270 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
26280 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
26290 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
262a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
262b0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
262c0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
262d0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
262e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
262f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
26300 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
26310 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
26320 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
26330 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26340 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
26350 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
26360 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
26370 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
26380 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
26390 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
263a0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
263b0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
263c0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
263d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
263e0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
263f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26400 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
26410 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
26420 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
26430 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
26440 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
26450 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
26460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
26470 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
26480 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
26490 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
264a0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
264b0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
264c0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
264d0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
264e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
264f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
26500 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
26510 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
26520 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
26530 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
26540 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
26550 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
26560 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
26570 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
26580 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
26590 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
265a0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
265b0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
265c0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
265d0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
265e0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
265f0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
26600 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
26610 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
26620 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
26630 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
26640 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
26650 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
26660 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
26670 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
26680 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
26690 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
266a0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
266b0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
266c0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
266d0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
266e0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
266f0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
26700 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
26710 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
26720 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
26730 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
26740 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
26750 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
26760 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
26770 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
26780 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
26790 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
267a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
267b0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
267c0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
267d0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
267e0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
267f0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
26800 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
26810 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
26820 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
26830 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
26840 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26850 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
26860 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26870 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
26880 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
26890 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
268a0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
268b0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
268c0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
268d0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
268e0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
268f0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
26900 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
26910 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
26920 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26930 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
26940 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26950 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
26960 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
26970 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
26980 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
26990 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
269a0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
269b0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
269c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
269d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
269e0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
269f0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26a00 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
26a10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
26a20 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
26a30 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
26a40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
26a50 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
26a60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
26a70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26a80 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
26a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26aa0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26ab0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26ac0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
26ad0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
26ae0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
26af0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
26b00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
26b10 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
26b20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
26b30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26b40 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
26b50 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
26b60 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 69  **.** Implementi
26b70 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
26b80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
26b90 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
26ba0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
26bb0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
26bc0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
26bd0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
26be0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
26bf0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
26c00 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
26c10 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
26c20 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
26c30 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
26c40 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
26c50 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
26c60 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
26c70 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
26c80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
26c90 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
26ca0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
26cb0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
26cc0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
26cd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
26ce0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
26cf0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
26d00 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
26d10 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
26d20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
26d30 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
26d40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
26d50 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
26d60 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
26d70 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
26d80 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
26d90 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
26da0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
26db0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
26dc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
26dd0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
26de0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
26df0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
26e00 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
26e10 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
26e20 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
26e30 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
26e40 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
26e50 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
26e60 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
26e70 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
26e80 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
26e90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
26ea0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
26eb0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
26ec0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
26ed0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
26ee0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
26ef0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
26f00 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
26f10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
26f20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
26f30 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
26f40 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
26f50 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
26f60 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ry allocate erro
26f70 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
26f80 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
26f90 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
26fa0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
26fb0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
26fc0 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
26fd0 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
26fe0 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
26ff0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
27000 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
27010 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
27020 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
27030 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
27040 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
27050 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
27060 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
27070 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
27080 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
27090 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
270a0 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ation.)^.**.** ^
270b0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
270c0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
270d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
270e0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
270f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27100 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
27110 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
27120 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
27130 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
27140 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
27150 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
27160 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
27170 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
27180 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
27190 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
271a0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
271b0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
271c0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
271d0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
271e0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
271f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
27200 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
27210 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
27220 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
27230 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
27240 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
27250 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
27260 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
27270 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27280 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
27290 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
272a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
272b0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
272c0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
272d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
272e0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
272f0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
27300 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
27310 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
27320 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
27330 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
27340 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
27350 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
27360 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
27370 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
27380 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
27390 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
273a0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
273b0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
273c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
273d0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
273e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
273f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
27400 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
27410 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
27420 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27430 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27440 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
27450 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
27460 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
27470 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
27480 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
27490 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
274a0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
274b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
274c0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
274d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
274e0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
274f0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
27500 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
27510 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
27520 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
27530 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
27540 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27550 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
27560 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27570 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
27580 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
27590 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
275a0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
275b0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
275c0 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
275d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
275e0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
275f0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
27600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
27610 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
27620 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
27630 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
27640 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
27650 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
27660 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
27670 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
27680 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
27690 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
276a0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
276b0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
276c0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
276d0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
276e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
276f0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
27700 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
27710 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
27720 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
27730 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
27740 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
27750 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
27760 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
27770 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
27780 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
27790 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
277a0 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
277b0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
277c0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
277d0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
277e0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
277f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
27800 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
27810 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
27820 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
27830 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
27840 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
27850 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
27860 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
27870 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
27880 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
27890 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
278a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
278b0 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
278c0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
278d0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
278e0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
278f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27900 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
27910 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27920 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27930 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
27940 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
27950 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
27960 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
27970 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
27980 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
27990 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
279a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
279b0 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74  tion. ^If no met
279c0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
279d0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
279e0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
279f0 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
27a00 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
27a10 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
27a20 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
27a30 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
27a40 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
27a50 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
27a60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
27a70 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
27a80 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
27a90 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
27aa0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
27ab0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
27ac0 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
27ad0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
27ae0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
27af0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
27b00 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
27b10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
27b20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27b30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27b40 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
27b50 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
27b60 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
27b70 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
27b80 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
27b90 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
27ba0 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20  stroyed..** ^If 
27bb0 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
27bc0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
27bd0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
27be0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
27bf0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
27c00 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27c10 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
27c20 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
27c30 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
27c40 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
27c50 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
27c60 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
27c70 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
27c80 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
27c90 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
27ca0 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
27cb0 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
27cc0 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
27cd0 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
27ce0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
27cf0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
27d00 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
27d10 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20  ime.  ^The only 
27d20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
27d30 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
27d40 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
27d50 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
27d60 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
27d70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
27d80 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
27d90 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
27da0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
27db0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
27dc0 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
27dd0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
27de0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
27df0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
27e00 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
27e10 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a  parameters].)^.*
27e20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27e30 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
27e40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
27e50 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
27e60 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
27e70 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
27e80 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
27e90 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
27ea0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27eb0 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
27ec0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
27ed0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27ee0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
27ef0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
27f00 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
27f10 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
27f20 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
27f30 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
27f40 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
27f50 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
27f60 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
27f70 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
27f80 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
27f90 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
27fa0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
27fb0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
27fc0 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
27fd0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
27fe0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
27ff0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
28000 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
28010 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
28020 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
28030 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
28040 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
28050 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
28060 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
28070 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
28080 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
28090 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
280a0 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
280b0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
280c0 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
280d0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
280e0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
280f0 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
28100 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
28110 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
28120 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
28130 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
28140 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
28150 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
28160 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
28170 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
28180 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
28190 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
281a0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
281b0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
281c0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
281d0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
281e0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
281f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
28200 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
28210 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
28220 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
28230 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
28240 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
28250 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
28260 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
28270 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
28280 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
28290 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
282a0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
282b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
282c0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
282d0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
282e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
282f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
28300 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
28310 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
28320 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
28330 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
28340 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
28350 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
28360 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
28370 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
28380 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
28390 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
283a0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
283b0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
283c0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
283d0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
283e0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
283f0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
28400 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
28410 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
28420 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
28430 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
28440 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
28450 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
28460 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28470 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
28480 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
28490 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
284a0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
284b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
284c0 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
284d0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
284e0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
284f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
28500 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
28510 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
28520 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
28530 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
28540 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28550 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28560 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
28570 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
28580 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
28590 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
285a0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
285b0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
285c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
285d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
285e0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
285f0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
28600 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
28610 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
28620 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28630 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
28640 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
28650 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
28660 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
28670 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28680 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28690 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
286a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
286b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
286c0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
286d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
286e0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
286f0 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
28700 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
28710 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
28720 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
28730 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
28740 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
28750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28760 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
28770 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
28780 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
28790 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
287a0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
287b0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
287c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
287d0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
287e0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
287f0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
28800 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
28810 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
28820 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
28830 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
28840 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
28850 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
28860 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28870 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
28880 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28890 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
288a0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
288b0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
288c0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
288d0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
288e0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
288f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
28900 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
28910 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28920 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
28930 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
28940 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
28950 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
28960 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
28970 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
28980 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
28990 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
289a0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
289b0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
289c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
289d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
289e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
289f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
28a00 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
28a10 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
28a20 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28a30 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
28a40 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
28a50 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
28a60 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
28a70 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
28a80 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
28a90 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
28aa0 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
28ab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28ac0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
28ad0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
28ae0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
28af0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
28b00 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
28b10 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
28b20 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
28b30 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
28b40 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
28b50 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
28b60 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
28b70 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
28b80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28b90 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
28ba0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28bb0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
28bc0 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
28bd0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
28be0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28bf0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
28c00 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
28c10 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
28c20 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
28c30 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
28c40 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
28c50 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
28c60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28c70 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
28c80 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
28c90 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
28ca0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
28cb0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
28cc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
28cd0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
28ce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28cf0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
28d00 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
28d10 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
28d20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28d30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28d40 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
28d50 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
28d60 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
28d70 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
28d80 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
28d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28da0 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
28db0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
28dc0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
28dd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28de0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
28df0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
28e00 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
28e10 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
28e20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
28e30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28e40 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
28e50 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
28e60 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
28e70 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
28e80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28e90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
28ea0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
28eb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28ec0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
28ed0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
28ee0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
28ef0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
28f00 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
28f10 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
28f20 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
28f30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
28f40 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28f50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28f60 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
28f70 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
28f80 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
28f90 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
28fa0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
28fb0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
28fc0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
28fd0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
28fe0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
28ff0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
29000 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
29010 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
29020 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
29030 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
29040 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
29050 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
29060 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
29070 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
29080 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29090 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
290a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
290b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
290c0 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
290d0 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
290e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
290f0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
29100 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
29110 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
29120 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
29130 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29140 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29150 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
29160 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
29170 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
29180 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
29190 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
291a0 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
291b0 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
291c0 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
291d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
291e0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
291f0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
29200 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
29210 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29220 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29230 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
29240 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
29250 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
29260 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
29270 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
29280 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
29290 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
292a0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
292b0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
292c0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
292d0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
292e0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
292f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
29300 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29310 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
29320 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
29330 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
29340 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
29350 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
29360 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
29370 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
29380 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
29390 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
293a0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
293b0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
293c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
293d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
293e0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
293f0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
29400 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
29410 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
29420 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
29430 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
29440 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
29450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29460 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
29470 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
29480 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
29490 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
294a0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
294b0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
294c0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
294d0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
294e0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
294f0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
29500 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
29510 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
29520 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29530 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29540 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29550 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
29560 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
29570 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29580 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
29590 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
295a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
295b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
295c0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
295d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
295e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
295f0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
29600 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
29610 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
29620 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
29630 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
29640 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
29650 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
29660 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
29670 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
29680 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
29690 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
296a0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
296b0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
296c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
296d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
296e0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
296f0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
29700 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29710 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29720 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
29730 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
29740 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
29750 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
29760 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
29770 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
29780 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
29790 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
297a0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
297b0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
297c0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
297d0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
297e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
297f0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
29800 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
29810 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
29820 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
29830 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
29840 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
29850 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
29860 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29870 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
29880 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
29890 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
298a0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
298b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
298c0 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
298d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
298e0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
298f0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
29900 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
29910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29920 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
29930 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
29940 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
29950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29960 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
29970 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
29980 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29990 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
299a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
299b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
299c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
299d0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
299e0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
299f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29a00 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
29a10 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
29a20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29a30 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
29a40 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
29a50 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
29a60 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
29a70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
29a80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29a90 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
29aa0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29ab0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
29ac0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29ad0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29ae0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
29af0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29b00 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
29b10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29b20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29b30 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
29b40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29b50 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
29b60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29b70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
29b80 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
29b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29ba0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
29bb0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
29bc0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29bd0 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
29be0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
29bf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
29c00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
29c10 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
29c20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29c30 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
29c40 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
29c50 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
29c60 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ences.**.** Thes
29c70 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
29c80 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20  used to add new 
29c90 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
29ca0 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64  ces to the.** [d
29cb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29cc0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
29cd0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
29ce0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
29cf0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
29d00 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
29d10 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
29d20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
29d30 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
29d40 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29d50 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
29d60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29d70 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
29d80 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
29d90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29da0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e  collation16(). ^
29db0 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
29dc0 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
29dd0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
29de0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
29df0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  nt..**.** ^The t
29e00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
29e10 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
29e20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
29e30 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
29e40 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72  ITE_UTF16LE], or
29e50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
29e60 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
29e70 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
29e80 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
29e90 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
29ea0 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
29eb0 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
29ec0 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
29ed0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
29ee0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
29ef0 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
29f00 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a  pectively. ^The.
29f10 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
29f20 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
29f30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74  [SQLITE_UTF16] t
29f40 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
29f50 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65  the routine.** e
29f60 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
29f70 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72  to be UTF-16 str
29f80 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69  ings in the nati
29f90 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f  ve byte order, o
29fa0 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  r the.** argumen
29fb0 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45  t can be [SQLITE
29fc0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
29fd0 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f  if the.** the ro
29fe0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
29ff0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
2a000 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
2a010 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
2a020 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
2a030 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
2a040 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
2a050 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
2a060 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
2a070 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2a080 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
2a090 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55  t.  ^If it is NU
2a0a0 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
2a0b0 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
2a0c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2a0d0 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
2a0e0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
2a0f0 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
2a100 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d  e)..** ^Each tim
2a110 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
2a120 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
2a130 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
2a140 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
2a150 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
2a160 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
2a170 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
2a180 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
2a190 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
2a1a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a1b0 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
2a1c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a1d0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
2a1e0 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20   ^The remaining 
2a1f0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2a200 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
2a210 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
2a220 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
2a230 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
2a240 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
2a250 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
2a260 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
2a270 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
2a280 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
2a290 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2a2a0 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
2a2b0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
2a2c0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
2a2d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2a2e0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
2a2f0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
2a300 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
2a310 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
2a320 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
2a330 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
2a340 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
2a350 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
2a360 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
2a370 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
2a380 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
2a390 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
2a3a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2a3b0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
2a3c0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
2a3d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2a3e0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
2a3f0 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
2a400 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
2a410 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
2a420 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
2a430 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65  lation.  ^The de
2a440 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2a450 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
2a460 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
2a470 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
2a480 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
2a490 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a4a0 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
2a4b0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
2a4c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2a4d0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f  ion_v2()..** ^Co
2a4e0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
2a4f0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
2a500 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
2a510 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
2a520 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
2a530 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
2a540 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
2a550 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a560 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
2a570 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2a580 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
2a590 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2a5a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a5b0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2a5c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2a5d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2a5e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2a5f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2a600 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2a610 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a620 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2a630 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2a640 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2a650 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2a660 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2a670 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2a680 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a690 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2a6a0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2a6b0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2a6c0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2a6d0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2a6e0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2a6f0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2a700 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
2a710 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2a720 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
2a730 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a740 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2a750 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2a760 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
2a770 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2a780 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2a790 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2a7a0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2a7b0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2a7c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a7d0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
2a7e0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
2a7f0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
2a800 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
2a810 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
2a820 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
2a830 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
2a840 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
2a850 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
2a860 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
2a870 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
2a880 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
2a890 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
2a8a0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2a8b0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
2a8c0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
2a8d0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
2a8e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2a8f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
2a900 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
2a910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2a920 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
2a930 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
2a940 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
2a950 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
2a960 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2a970 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
2a980 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
2a990 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
2a9a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2a9b0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
2a9c0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
2a9d0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2a9e0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
2a9f0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
2aa00 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
2aa10 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
2aa20 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
2aa30 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
2aa40 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2aa50 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
2aa60 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
2aa70 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2aa80 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
2aa90 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2aaa0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2aab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2aac0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2aad0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2aae0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2aaf0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2ab00 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2ab10 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2ab20 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
2ab30 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2ab40 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
2ab50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2ab60 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
2ab70 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
2ab80 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
2ab90 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
2aba0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2abb0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
2abc0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
2abd0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2abe0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2abf0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
2ac00 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2ac10 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
2ac20 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
2ac30 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
2ac40 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
2ac50 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
2ac60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2ac70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
2ac80 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2ac90 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
2aca0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2acb0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2acc0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
2acd0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ace0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2acf0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2ad00 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2ad10 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2ad20 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2ad30 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
2ad40 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2ad50 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
2ad60 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
2ad70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2ad80 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2ad90 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
2ada0 29 3b 0a 0a 23 69 66 20 53 51 4c 49 54 45 5f 48  );..#if SQLITE_H
2adb0 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
2adc0 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
2add0 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
2ade0 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
2adf0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
2ae00 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
2ae10 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
2ae20 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
2ae30 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
2ae40 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
2ae50 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
2ae60 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
2ae70 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
2ae80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ae90 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
2aea0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2aeb0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2aec0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2aed0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2aee0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2aef0 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
2af00 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
2af10 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
2af20 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
2af30 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
2af40 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
2af50 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
2af60 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
2af70 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
2af80 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
2af90 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
2afa0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
2afb0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
2afc0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2afd0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2afe0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2aff0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2b000 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2b010 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
2b020 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
2b030 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2b040 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2b050 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
2b060 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
2b070 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
2b080 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
2b090 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
2b0a0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
2b0b0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
2b0c0 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
2b0d0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
2b0e0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
2b0f0 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
2b100 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
2b110 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
2b120 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
2b130 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
2b140 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
2b150 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
2b160 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
2b170 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
2b180 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
2b190 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
2b1a0 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
2b1b0 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
2b1c0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
2b1d0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
2b1e0 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
2b1f0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
2b200 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
2b210 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
2b220 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
2b230 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
2b240 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
2b250 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
2b260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
2b270 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
2b280 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
2b290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b2a0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
2b2b0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
2b2c0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
2b2d0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2b2e0 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
2b2f0 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
2b300 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
2b310 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
2b320 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ameter..**.** ^I
2b330 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2b340 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2b350 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2b360 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
2b370 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2b380 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2b390 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2b3a0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
2b3b0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
2b3c0 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62  econd. ^The numb
2b3d0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2b3e0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
2b3f0 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
2b400 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
2b410 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
2b420 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2b430 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
2b440 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
2b450 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
2b460 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
2b470 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
2b480 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
2b490 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
2b4a0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
2b4b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b4c0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
2b4d0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
2b4e0 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
2b4f0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
2b500 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
2b510 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2b520 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
2b530 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
2b540 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
2b550 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
2b560 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
2b570 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
2b580 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
2b590 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
2b5a0 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
2b5b0 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
2b5c0 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
2b5d0 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
2b5e0 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
2b5f0 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
2b600 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
2b610 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
2b620 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
2b630 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
2b640 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
2b650 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
2b660 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2b670 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2b680 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
2b690 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
2b6a0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
2b6b0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
2b6c0 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
2b6d0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2b6e0 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
2b6f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b700 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
2b710 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
2b720 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
2b730 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
2b740 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
2b750 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
2b760 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
2b770 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
2b780 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
2b790 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
2b7a0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
2b7b0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
2b7c0 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
2b7d0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2b7e0 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
2b7f0 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
2b800 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
2b810 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2b820 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
2b830 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2b840 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
2b850 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
2b860 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2b870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2b880 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
2b890 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
2b8a0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2b8b0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
2b8c0 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
2b8d0 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
2b8e0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2b8f0 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
2b900 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
2b910 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
2b920 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
2b930 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
2b940 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
2b950 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
2b960 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b970 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
2b980 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
2b990 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
2b9a0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
2b9b0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
2b9c0 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
2b9d0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
2b9e0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2b9f0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2ba00 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
2ba10 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
2ba20 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
2ba30 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
2ba40 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
2ba50 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
2ba60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
2ba70 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
2ba80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2ba90 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
2baa0 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
2bab0 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
2bac0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
2bad0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2bae0 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
2baf0 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
2bb00 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
2bb10 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
2bb20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bb30 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
2bb40 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
2bb50 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
2bb60 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
2bb70 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
2bb80 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
2bb90 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
2bba0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
2bbb0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
2bbc0 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
2bbd0 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
2bbe0 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
2bbf0 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
2bc00 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
2bc10 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
2bc20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
2bc30 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
2bc40 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
2bc50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
2bc60 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
2bc70 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
2bc80 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
2bc90 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
2bca0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
2bcb0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
2bcc0 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
2bcd0 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
2bce0 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
2bcf0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
2bd00 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
2bd10 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
2bd20 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
2bd30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2bd40 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
2bd50 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
2bd60 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
2bd70 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
2bd80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
2bd90 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
2bda0 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
2bdb0 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
2bdc0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2bdd0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
2bde0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
2bdf0 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
2be00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2be10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2be20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
2be30 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
2be40 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
2be50 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
2be60 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
2be70 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
2be80 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2be90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
2bea0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
2beb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
2bec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bed0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
2bee0 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
2bef0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
2bf00 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
2bf10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf20 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
2bf30 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
2bf40 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
2bf50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bf60 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
2bf70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2bf80 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
2bf90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bfa0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
2bfb0 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
2bfc0 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
2bfd0 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
2bfe0 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
2bff0 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
2c000 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
2c010 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
2c020 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2c030 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
2c040 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
2c050 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2c060 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
2c070 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2c080 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
2c090 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c0a0 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74  ] after.** pStmt
2c0b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c0c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2c0d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20  onnection] pDb. 
2c0e0 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55   ^If pStmt is NU
2c0f0 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
2c100 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c110 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2c120 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
2c130 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
2c140 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2c150 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c160 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66  ection pDb.  ^If
2c170 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61   no prepared sta
2c180 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66  tement.** satisf
2c190 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
2c1a0 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
2c1b0 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ne, it returns N
2c1c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
2c1d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c1e0 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69  ion] pointer D i
2c1f0 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  n a call to.** [
2c200 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2c210 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66  t(D,S)] must ref
2c220 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61  er to an open da
2c230 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2c240 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74  tion and in part
2c250 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20  icular must not 
2c260 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
2c270 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74  r..*/.sqlite3_st
2c280 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74  mt *sqlite3_next
2c290 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70  _stmt(sqlite3 *p
2c2a0 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  Db, sqlite3_stmt
2c2b0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2c2c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
2c2d0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
2c2e0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2c2f0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2c300 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2c310 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2c320 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2c330 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2c340 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2c350 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2c360 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49  action is [COMMI
2c370 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a  T | committed]..
2c380 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2c390 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2c3a0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
2c3b0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2c3c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2c3d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c3e0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
2c3f0 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  en..** ^The sqli
2c400 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2c410 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2c420 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2c430 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
2c440 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
2c450 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
2c460 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b  ion is [ROLLBACK
2c470 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e   | rolled back].
2c480 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2c490 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2c4a0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
2c4b0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2c4c0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2c4d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2c4e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2c4f0 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70  idden..** ^The p
2c500 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
2c510 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
2c520 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
2c530 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
2c540 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
2c550 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  hook function re
2c560 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a  turns non-zero,.
2c570 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ** then the comm
2c580 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
2c590 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
2c5a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c5b0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2c5c0 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74  D,C,P) and sqlit
2c5d0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2c5e0 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
2c5f0 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20  s.** return the 
2c600 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
2c610 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2c620 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  l of the same fu
2c630 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65  nction.** on the
2c640 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2c650 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
2c660 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
2c670 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
2c680 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f   each function o
2c690 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n D..**.** The c
2c6a0 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
2c6b0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2c6c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2c6d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2c6e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c6f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2c700 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
2c710 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2c720 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2c730 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c740 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2c750 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2c760 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2c770 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2c780 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2c790 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2c7a0 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
2c7b0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
2c7c0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2c7d0 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
2c7e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c7f0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2c800 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2c810 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2c820 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c830 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2c840 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2c850 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2c860 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69  aph..**.** ^Regi
2c870 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
2c880 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2c890 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2c8a0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63  *.** ^When the c
2c8b0 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62  ommit hook callb
2c8c0 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ack routine retu
2c8d0 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43  rns zero, the [C
2c8e0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74  OMMIT].** operat
2c8f0 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74  ion is allowed t
2c900 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61  o continue norma
2c910 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f  lly.  ^If the co
2c920 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74  mmit hook.** ret
2c930 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
2c940 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  hen the [COMMIT]
2c950 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
2c960 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  to a [ROLLBACK].
2c970 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
2c980 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65  k hook is invoke
2c990 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20  d on a rollback 
2c9a0 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f  that results fro
2c9b0 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f  m a commit.** ho
2c9c0 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e  ok returning non
2c9d0 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69  -zero, just as i
2c9e0 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20  t would be with 
2c9f0 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61  any other rollba
2ca00 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  ck..**.** ^For t
2ca10 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
2ca20 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
2ca30 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
2ca40 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
2ca50 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
2ca60 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
2ca70 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
2ca80 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
2ca90 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
2caa0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
2cab0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
2cac0 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
2cad0 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
2cae0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
2caf0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
2cb00 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
2cb10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2cb20 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2cb30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2cb40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
2cb50 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ed..** ^The roll
2cb60 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
2cb70 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
2cb80 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2cb90 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
2cba0 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74  because a commit
2cbb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
2cbc0 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a  ed non-zero..**.
2cbd0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2cbe0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2cbf0 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2cc00 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2cc10 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2cc20 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2cc30 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2cc40 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2cc50 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2cc60 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2cc70 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2cc80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cc90 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2cca0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2ccb0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2ccc0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2ccd0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2cce0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2ccf0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2cd00 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2cd10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2cd20 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2cd30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2cd40 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2cd50 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2cd60 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2cd70 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2cd80 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2cd90 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2cda0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2cdb0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2cdc0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2cdd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2cde0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2cdf0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2ce00 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2ce10 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2ce20 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2ce30 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2ce40 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2ce50 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2ce60 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2ce70 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2ce80 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2ce90 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2cea0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2ceb0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2cec0 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2ced0 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2cee0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2cef0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2cf00 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2cf10 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2cf20 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2cf30 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2cf40 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2cf50 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2cf60 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2cf70 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2cf80 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2cf90 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2cfa0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2cfb0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2cfc0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2cfd0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2cfe0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2cff0 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2d000 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2d010 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2d020 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2d030 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2d040 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2d050 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2d060 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2d070 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2d080 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2d090 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2d0a0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2d0b0 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2d0c0 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2d0d0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2d0e0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2d0f0 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2d100 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2d110 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2d120 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2d130 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2d140 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2d150 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2d160 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2d170 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2d180 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2d190 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2d1a0 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2d1b0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2d1c0 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2d1d0 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2d1e0 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2d1f0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2d200 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2d210 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2d220 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2d230 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2d240 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2d250 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2d260 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2d270 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2d280 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2d290 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2d2a0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2d2b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2d2c0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2d2d0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2d2e0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2d2f0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2d300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2d310 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2d320 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2d330 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2d340 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2d350 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2d360 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2d370 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2d380 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2d390 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2d3a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2d3b0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2d3c0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2d3d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2d3e0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2d3f0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2d400 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2d410 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d420 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2d430 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2d440 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2d450 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2d460 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2d470 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2d480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d490 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2d4a0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2d4b0 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2d4c0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2d4d0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2d4e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d4f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2d500 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2d510 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2d520 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2d530 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2d540 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2d550 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2d560 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2d570 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2d580 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2d590 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2d5a0 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2d5b0 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
2d5c0 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2d5d0 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
2d5e0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
2d5f0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2d600 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2d610 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2d620 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2d630 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2d640 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2d650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2d660 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2d670 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2d680 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2d690 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2d6a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2d6b0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2d6c0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2d6d0 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
2d6e0 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
2d6f0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2d700 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2d710 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2d720 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2d730 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2d740 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2d750 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2d760 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2d770 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2d780 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2d790 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2d7a0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2d7b0 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
2d7c0 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2d7d0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2d7e0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2d7f0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2d800 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2d810 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2d820 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2d830 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d840 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2d850 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d860 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2d870 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2d880 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2d890 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2d8a0 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2d8b0 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
2d8c0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
2d8d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2d8e0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2d8f0 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2d900 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
2d910 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2d920 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2d930 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2d940 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
2d950 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2d960 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2d970 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2d980 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2d990 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2d9a0 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2d9b0 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2d9c0 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2d9d0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2d9e0 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2d9f0 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
2da00 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
2da10 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
2da20 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
2da30 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2da40 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2da50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2da60 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2da70 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
2da80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2da90 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2daa0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2dab0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2dac0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2dad0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2dae0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2daf0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2db00 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2db10 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2db20 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
2db30 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2db40 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2db50 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2db60 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2db70 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2db80 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2db90 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
2dba0 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2dbb0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2dbc0 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2dbd0 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2dbe0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2dbf0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2dc00 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2dc10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2dc20 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
2dc30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2dc40 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
2dc50 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
2dc60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dc70 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2dc80 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2dc90 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2dca0 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2dcb0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2dcc0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2dcd0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2dce0 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e  QLite..** ^If an
2dcf0 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
2dd00 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2dd10 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
2dd20 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
2dd30 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
2dd40 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2dd50 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
2dd60 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
2dd70 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
2dd80 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
2dd90 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
2dda0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2ddb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69  .**.** ^The limi
2ddc0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2ddd0 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  t" because if [s
2dde0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2ddf0 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2de00 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2de10 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2de20 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2de30 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2de40 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2de50 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2de60 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2de70 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2de80 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2de90 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2dea0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2deb0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2dec0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2ded0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2dee0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2def0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2df00 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2df10 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2df20 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2df30 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2df40 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2df50 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2df60 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2df70 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2df80 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2df90 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2dfa0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2dfb0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2dfc0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2dfd0 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2dfe0 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2dff0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2e000 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2e010 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2e020 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2e030 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2e040 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2e050 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2e060 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2e070 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2e080 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2e090 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2e0a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2e0b0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2e0c0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2e0d0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2e0e0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2e0f0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2e100 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2e110 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2e120 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2e130 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2e140 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2e150 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2e160 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2e170 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2e180 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2e190 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2e1a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2e1b0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2e1c0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2e1d0 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2e1e0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2e1f0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2e200 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2e210 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2e220 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2e230 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2e240 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2e250 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2e260 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2e270 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2e280 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2e290 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
2e2a0 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
2e2b0 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
2e2c0 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
2e2d0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
2e2e0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
2e2f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2e300 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2e310 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
2e320 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
2e330 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2e340 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
2e350 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2e360 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2e370 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2e380 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2e390 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
2e3a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2e3b0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2e3c0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2e3d0 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2e3e0 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
2e3f0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2e400 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2e410 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2e420 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2e430 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
2e440 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
2e450 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
2e460 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
2e470 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
2e480 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
2e490 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
2e4a0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
2e4b0 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
2e4c0 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
2e4d0 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
2e4e0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2e4f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2e500 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
2e510 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
2e520 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
2e530 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
2e540 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
2e550 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
2e560 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
2e570 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
2e580 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
2e590 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2e5a0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2e5b0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2e5c0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2e5d0 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2e5e0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2e5f0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2e600 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
2e610 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
2e620 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
2e630 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2e640 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2e650 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
2e660 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
2e670 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
2e680 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2e690 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2e6a0 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
2e6b0 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
2e6c0 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
2e6d0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2e6e0 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
2e6f0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
2e700 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
2e710 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
2e720 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
2e730 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
2e740 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
2e750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
2e760 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2e770 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2e780 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
2e790 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
2e7a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
2e7b0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2e7c0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2e7d0 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
2e7e0 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
2e7f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
2e800 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2e810 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2e820 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
2e830 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
2e840 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2e850 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
2e860 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2e870 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2e880 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2e890 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2e8a0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2e8b0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2e8c0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2e8d0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2e8e0 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2e8f0 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2e900 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2e910 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
2e920 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2e930 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2e940 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2e950 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2e960 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2e970 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2e980 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2e990 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2e9a0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2e9b0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2e9c0 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2e9d0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2e9e0 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2e9f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2ea00 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2ea10 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2ea20 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65  lumn. ^(If there
2ea30 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
2ea40 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49  itly declared [I
2ea50 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2ea60 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  EY] column, then
2ea70 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2ea80 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2ea90 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
2eaa0 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
2eab0 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
2eac0 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
2ead0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
2eae0 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
2eaf0 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
2eb00 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
2eb10 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
2eb20 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
2eb30 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  /pre>)^.**.** ^(
2eb40 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
2eb50 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
2eb60 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
2eb70 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
2eb80 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
2eb90 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
2eba0 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
2ebb0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
2ebc0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
2ebd0 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
2ebe0 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  d, an [error cod
2ebf0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
2ec00 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
2ec10 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74  age left.** in t
2ec20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2ec30 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20  nection] (to be 
2ec40 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
2ec50 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2ec60 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ).)^.**.** ^This
2ec70 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
2ec80 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2ec90 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2eca0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2ecb0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2ecc0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2ecd0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2ece0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
2ecf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
2ed00 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
2ed10 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
2ed20 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2ed30 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
2ed40 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ed50 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
2ed60 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2ed70 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
2ed80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ed90 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
2eda0 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
2edb0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2edc0 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
2edd0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
2ede0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
2edf0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
2ee00 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
2ee10 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
2ee20 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2ee30 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
2ee40 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
2ee50 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
2ee60 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
2ee70 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
2ee80 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2ee90 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
2eea0 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
2eeb0 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
2eec0 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
2eed0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2eee0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
2eef0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
2ef00 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
2ef10 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2ef20 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2ef30 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
2ef40 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
2ef50 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
2ef60 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
2ef70 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
2ef80 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
2ef90 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2efa0 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
2efb0 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
2efc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2efd0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2efe0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2eff0 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2f000 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2f010 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
2f020 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a  ed in the file z
2f030 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  File..**.** ^The
2f040 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2f050 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63  zProc..** ^zProc
2f060 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
2f070 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
2f080 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
2f090 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73  oint.** defaults
2f0a0 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
2f0b0 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
2f0c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2f0d0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2f0e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2f0f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
2f100 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
2f110 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2f120 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
2f130 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e  wrong..** ^If an
2f140 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
2f150 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
2f160 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  t 0, then the.**
2f170 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2f180 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2f190 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2f1a0 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a  mpt to.** fill *
2f1b0 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
2f1c0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2f1d0 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
2f1e0 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
2f1f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f200 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69  oc()]. The calli
2f210 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  ng function.** s
2f220 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
2f230 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e  memory by callin
2f240 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
2f250 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  )]..**.** ^Exten
2f260 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
2f270 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
2f280 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
2f290 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2f2a0 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
2f2b0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
2f2c0 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  I,.** otherwise 
2f2d0 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
2f2e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f2f0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c   See also the [l
2f300 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2f310 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
2f320 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
2f330 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
2f340 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2f350 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
2f360 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
2f370 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
2f380 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
2f390 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2f3a0 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
2f3b0 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
2f3c0 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
2f3d0 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
2f3e0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
2f3f0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
2f400 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
2f410 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
2f420 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
2f430 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
2f440 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
2f450 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
2f460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f470 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
2f480 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
2f490 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61  ding.**.** ^So a
2f4a0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
2f4b0 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
2f4c0 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
2f4d0 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
2f4e0 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
2f4f0 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
2f500 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
2f510 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
2f520 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
2f530 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
2f540 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
2f550 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
2f560 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
2f570 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
2f580 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
2f590 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2f5a0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
2f5b0 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
2f5c0 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
2f5d0 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
2f5e0 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b  efault. See tick
2f5f0 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61  et #1863..** ^Ca
2f600 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
2f610 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2f620 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
2f630 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
2f640 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
2f650 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
2f660 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
2f670 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
2f680 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  * it back off ag
2f690 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
2f6a0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2f6b0 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
2f6c0 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
2f6d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f6e0 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
2f6f0 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
2f700 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
2f710 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
2f720 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
2f730 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
2f740 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
2f750 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
2f760 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
2f770 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
2f780 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
2f790 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
2f7a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f7b0 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ns]..**.** ^(Thi
2f7c0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
2f7d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2f7e0 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  e extension entr
2f7f0 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e  y point.** in an
2f800 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f   array that is o
2f810 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2f820 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
2f830 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a    That memory.**
2f840 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   is deallocated 
2f850 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  by [sqlite3_rese
2f860 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2f870 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
2f880 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  is function regi
2f890 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
2f8a0 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
2f8b0 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  hat is.** automa
2f8c0 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
2f8d0 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
2f8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f8f0 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65  ion].** is opene
2f900 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2f910 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2f920 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
2f930 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
2f940 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70  n_v2()]..** ^Dup
2f950 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
2f960 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
2f970 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
2f980 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70  outine.** multip
2f990 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
2f9a0 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
2f9b0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
2f9c0 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65   ^Automatic exte
2f9d0 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
2f9e0 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
2f9f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2fa00 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
2fa10 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
2fa20 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
2fa30 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2fa40 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
2fa50 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
2fa60 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
2fa70 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ion disables all
2fa80 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
2fa90 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63  stered automatic
2faa0 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  .** extensions. 
2fab0 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  It undoes the ef
2fac0 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
2fad0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75  r.** [sqlite3_au
2fae0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
2faf0 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  calls.)^.**.** ^
2fb00 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2fb10 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
2fb20 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
2fb30 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
2fb40 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
2fb50 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2fb60 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a  (void);../*.****
2fb70 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
2fb80 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
2fb90 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
2fba0 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
2fbb0 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  *.**.** The inte
2fbc0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
2fbd0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2fbe0 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
2fbf0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
2fc00 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
2fc10 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
2fc20 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
2fc30 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
2fc40 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
2fc50 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
2fc60 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
2fc70 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
2fc80 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
2fc90 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
2fca0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2fcb0 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
2fcc0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
2fcd0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
2fce0 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
2fcf0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
2fd00 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
2fd10 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
2fd20 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
2fd30 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
2fd40 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
2fd50 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
2fd60 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2fd70 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
2fd80 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2fd90 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2fda0 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
2fdb0 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
2fdc0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2fdd0 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
2fde0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
2fdf0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2fe00 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
2fe10 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
2fe20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
2fe30 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65  rtual Table Obje
2fe40 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2fe50 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
2fe60 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
2fe70 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d  dule}.** EXPERIM
2fe80 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ENTAL.**.** This
2fe90 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65   structure, some
2fea0 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61  times called a a
2feb0 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   "virtual table 
2fec0 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66  module", .** def
2fed0 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65  ines the impleme
2fee0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69  ntation of a [vi
2fef0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20  rtual tables].  
2ff00 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
2ff10 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74  re consists most
2ff20 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f  ly of methods fo
2ff30 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
2ff40 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74  .** ^A virtual t
2ff50 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63  able module is c
2ff60 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e  reated by fillin
2ff70 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e  g in a persisten
2ff80 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  t.** instance of
2ff90 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
2ffa0 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f  and passing a po
2ffb0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  inter to that in
2ffc0 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71  stance.** to [sq
2ffd0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2ffe0 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ule()] or [sqlit
2fff0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
30000 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v2()]..** ^The 
30010 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d  registration rem
30020 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ains valid until
30030 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
30040 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a  by a different.*
30050 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69  * module or unti
30060 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  l the [database 
30070 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73  connection] clos
30080 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  es.  The content
30090 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75  .** of this stru
300a0 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63  cture must not c
300b0 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69  hange while it i
300c0 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
300d0 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73  h.** any databas
300e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f  e connection..*/
300f0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
30100 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
30110 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
30120 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
30130 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
30140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
30150 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
30160 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
30170 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30180 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
30190 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
301a0 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
301b0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
301c0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
301d0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
301e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
301f0 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
30200 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
30210 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
30220 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
30230 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
30240 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
30250 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
30260 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
30270 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
30280 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30290 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
302a0 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
302b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
302c0 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
302d0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
302e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
302f0 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
30300 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
30310 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30320 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
30330 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
30340 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
30350 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
30360 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
30370 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
30380 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
30390 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
303a0 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
303b0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
303c0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
303d0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
303e0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
303f0 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
30400 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
30410 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30420 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
30430 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
30440 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
30450 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
30460 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
30470 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
30480 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
30490 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
304a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
304b0 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
304c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
304d0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
304e0 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
304f0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30500 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
30510 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30520 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
30530 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
30540 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30550 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
30560 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
30570 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
30580 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
30590 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
305a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
305b0 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
305c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
305d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
305e0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
305f0 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
30600 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
30610 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
30620 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
30630 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
30640 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
30650 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
30660 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
30670 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f  rmation.** KEYWO
30680 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64  RDS: sqlite3_ind
30690 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52  ex_info.** EXPER
306a0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
306b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
306c0 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
306d0 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74  nd its substruct
306e0 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a  ures is used to.
306f0 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74  ** pass informat
30700 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63  ion into and rec
30710 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66  eive the reply f
30720 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e  rom the [xBestIn
30730 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  dex].** method o
30740 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
30750 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65  le module].  The
30760 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a   fields under **
30770 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65  Inputs** are the
30780 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42  .** inputs to xB
30790 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65  estIndex and are
307a0 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65   read-only.  xBe
307b0 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20  stIndex inserts 
307c0 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  its.** results i
307d0 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74  nto the **Output
307e0 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a  s** fields..**.*
307f0 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61  * ^(The aConstra
30800 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f  int[] array reco
30810 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rds WHERE clause
30820 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20   constraints of 
30830 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  the form:.**.** 
30840 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65  <pre>column OP e
30850 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  xpr</pre>.**.** 
30860 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26  where OP is =, &
30870 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b  lt;, &lt;=, &gt;
30880 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e  , or &gt;=.)^  ^
30890 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20  (The particular 
308a0 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73  operator is.** s
308b0 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72  tored in aConstr
308c0 61 69 6e 74 5b 5d 2e 6f 70 2e 29 5e 20 20 5e 28  aint[].op.)^  ^(
308d0 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
308e0 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
308f0 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61  d in.** aConstra
30900 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e  int[].iColumn.)^
30910 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b    ^(aConstraint[
30920 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45  ].usable is TRUE
30930 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20   if the.** expr 
30940 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  on the right-han
30950 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76  d side can be ev
30960 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75  aluated (and thu
30970 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  s the constraint
30980 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61  .** is usable) a
30990 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63  nd false if it c
309a0 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  annot.)^.**.** ^
309b0 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75  The optimizer au
309c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65  tomatically inve
309d0 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65  rts terms of the
309e0 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63   form "expr OP c
309f0 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61  olumn".** and ma
30a00 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69  kes other simpli
30a10 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65  fications to the
30a20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e   WHERE clause in
30a30 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a   an attempt to.*
30a40 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48  * get as many WH
30a50 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
30a60 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73   into the form s
30a70 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f  hown above as po
30a80 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20  ssible..** ^The 
30a90 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
30aa0 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
30ab0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
30ac0 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  rms that are.** 
30ad0 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20  relevant to the 
30ae0 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
30af0 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
30b00 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ueried..**.** ^I
30b10 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
30b20 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
30b30 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  ause is stored i
30b40 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a  n aOrderBy[]..**
30b50 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61   ^Each term of a
30b60 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20  OrderBy records 
30b70 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  a column of the 
30b80 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e  ORDER BY clause.
30b90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73  .**.** The [xBes
30ba0 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d  tIndex] method m
30bb0 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
30bc0 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
30bd0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
30be0 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
30bf0 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
30c00 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61   xFilter.  ^If a
30c10 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
30c20 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
30c30 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
30c40 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
30c50 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
30c60 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
30c70 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
30c80 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
30c90 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e  argv.  ^(If aCon
30ca0 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
30cb0 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
30cc0 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
30cd0 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
30ce0 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
30cf0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed by the.** vir
30d00 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
30d10 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67  s not checked ag
30d20 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e  ain by SQLite.)^
30d30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e  .**.** ^The idxN
30d40 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61  um and idxPtr va
30d50 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65  lues are recorde
30d60 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74  d and passed int
30d70 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65  o the.** [xFilte
30d80 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b  r] method..** ^[
30d90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
30da0 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
30db0 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e  idxPtr if and on
30dc0 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46  ly if.** needToF
30dd0 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75  reeIdxPtr is tru
30de0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72  e..**.** ^The or
30df0 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
30e00 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
30e10 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b  from [xFilter]/[
30e20 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75  xNext] will occu
30e30 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72  r in.** the corr
30e40 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74  ect order to sat
30e50 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42  isfy the ORDER B
30e60 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74  Y clause so that
30e70 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20   no separate.** 
30e80 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20  sorting step is 
30e90 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
30ea0 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f  ^The estimatedCo
30eb0 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
30ec0 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
30ed0 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
30ee0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
30ef0 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
30f00 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
30f10 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
30f20 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
30f30 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
30f40 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
30f50 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
30f60 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
30f70 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
30f80 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
30f90 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
30fa0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
30fb0 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
30fc0 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e    int nConstrain
30fd0 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t;           /* 
30fe0 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
30ff0 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
31000 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
31010 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
31020 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74  raint {.     int
31030 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
31040 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
31050 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69   on left-hand si
31060 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74  de of constraint
31070 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
31080 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20  d char op;      
31090 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74     /* Constraint
310a0 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20   operator */.   
310b0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
310c0 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
310d0 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
310e0 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
310f0 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65   */.     int iTe
31100 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20  rmOffset;       
31110 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
31120 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64  nally - xBestInd
31130 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65  ex should ignore
31140 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
31150 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
31160 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45   /* Table of WHE
31170 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
31180 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  aints */.  int n
31190 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
311a0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
311b0 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
311c0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
311d0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
311e0 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
311f0 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
31200 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
31210 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
31220 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
31230 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
31240 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
31250 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
31260 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
31270 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
31280 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
31290 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
312a0 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  /.  /* Outputs *
312b0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
312c0 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
312d0 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
312e0 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
312f0 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
31300 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
31310 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
31320 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
31330 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
31340 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
31350 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
31360 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
31370 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  nt */.  } *aCons
31380 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69  traintUsage;.  i
31390 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20  nt idxNum;      
313a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
313b0 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e  ber used to iden
313c0 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a  tify the index *
313d0 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72  /.  char *idxStr
313e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
313f0 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62  * String, possib
31400 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
31410 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20   sqlite3_malloc 
31420 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46  */.  int needToF
31430 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20  reeIdxStr;      
31440 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75  /* Free idxStr u
31450 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
31460 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20  e() if true */. 
31470 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73   int orderByCons
31480 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54  umed;       /* T
31490 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73  rue if output is
314a0 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64   already ordered
314b0 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74   */.  double est
314c0 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20  imatedCost;     
314d0 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f   /* Estimated co
314e0 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  st of using this
314f0 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65   index */.};.#de
31500 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
31510 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
31520 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
31530 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
31540 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
31550 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
31560 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
31570 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
31580 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
31590 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
315a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
315b0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
315c0 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
315d0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
315e0 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
315f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31600 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
31610 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
31620 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 45 58 50 45  entation.** EXPE
31630 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e  RIMENTAL.**.** ^
31640 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
31650 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  re used to regis
31660 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ter a new [virtu
31670 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
31680 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c   name..** ^Modul
31690 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
316a0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
316b0 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
316c0 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
316d0 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
316e0 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20  dule and before 
316f0 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
31700 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
31710 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
31720 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  odule..**.** ^Th
31730 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
31740 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
31750 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31760 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
31770 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
31780 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  st parameter.  ^
31790 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
317a0 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
317b0 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
317c0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
317d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
317e0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
317f0 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  to.** the implem
31800 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
31810 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
31820 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66  odule].   ^The f
31830 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  ourth.** paramet
31840 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
31850 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  ry client data p
31860 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
31870 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
31880 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61   into the [xCrea
31890 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
318a0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  t] methods of th
318b0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
318c0 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61  module.** when a
318d0 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
318e0 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63  le is be being c
318f0 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74  reated or reinit
31900 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ialized..**.** ^
31910 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
31920 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69  te_module_v2() i
31930 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66  nterface has a f
31940 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77  ifth parameter w
31950 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
31960 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
31970 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c  ctor for the pCl
31980 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69  ientData.  ^SQLi
31990 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
319a0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
319b0 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
319c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
319d0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
319e0 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
319f0 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
31a00 6e 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c 69  nter.  ^The sqli
31a10 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
31a20 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
31a30 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
31a40 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
31a50 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74  _module_v2() wit
31a60 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74  h a NULL.** dest
31a70 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54  ructor..*/.SQLIT
31a80 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
31a90 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
31aa0 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
31ab0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
31ac0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
31ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
31ae0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
31af0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
31b00 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
31b10 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
31b20 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
31b30 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
31b40 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
31b50 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
31b60 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
31b70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
31b80 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
31b90 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
31ba0 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 53 51  Connect */.);.SQ
31bb0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
31bc0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  L int sqlite3_cr
31bd0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a  eate_module_v2(.
31be0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
31bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31c00 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
31c10 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
31c20 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
31c30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
31c40 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
31c50 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
31c60 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
31c70 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
31c80 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
31c90 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
31ca0 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
31cb0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69  ,         /* Cli
31cc0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
31cd0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
31ce0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
31cf0 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a  y)(void*)     /*
31d00 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74   Module destruct
31d10 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29  or function */.)
31d20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31d30 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
31d40 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74   Instance Object
31d50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
31d60 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58  lite3_vtab.** EX
31d70 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
31d80 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
31d90 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
31da0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
31db0 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20  s a subclass.** 
31dc0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74  of this object t
31dd0 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
31de0 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
31df0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74  .** of the [virt
31e00 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63  ual table].  Eac
31e10 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
31e20 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74  ** be tailored t
31e30 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
31e40 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
31e50 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31e60 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73  n..** The purpos
31e70 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
31e80 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
31e90 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
31ea0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d   that are.** com
31eb0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  mon to all modul
31ec0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31ed0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61  s..**.** ^Virtua
31ee0 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
31ef0 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
31f00 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
31f10 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
31f20 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
31f30 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
31f40 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e  f()] to zErrMsg.
31f50 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f    The method sho
31f60 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65  uld.** take care
31f70 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20   that any prior 
31f80 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20  string is freed 
31f90 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
31fa0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
31fb0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
31fc0 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
31fd0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41   to zErrMsg.  ^A
31fe0 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
31ff0 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c  essage.** is del
32000 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65  ivered up to the
32010 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74   client applicat
32020 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20  ion, the string 
32030 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
32040 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62  cally.** freed b
32050 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  y sqlite3_free()
32060 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67   and the zErrMsg
32070 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a   field will be z
32080 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74  eroed..*/.struct
32090 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a   sqlite3_vtab {.
320a0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
320b0 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b  module *pModule;
320c0 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20    /* The module 
320d0 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c  for this virtual
320e0 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20   table */.  int 
320f0 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20  nRef;           
32100 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
32110 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f  O LONGER USED */
32120 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  .  char *zErrMsg
32130 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
32140 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73     /* Error mess
32150 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  age from sqlite3
32160 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20  _mprintf() */.  
32170 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
32180 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32190 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
321a0 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
321b0 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
321c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
321d0 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f  tual Table Curso
321e0 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  r Object.** KEYW
321f0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
32200 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75  ab_cursor {virtu
32210 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d  al table cursor}
32220 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
32230 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69  .**.** Every [vi
32240 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
32250 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  le] implementati
32260 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
32270 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c  ss of the.** fol
32280 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
32290 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72   to describe cur
322a0 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20  sors that point 
322b0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72  into the.** [vir
322c0 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20  tual table] and 
322d0 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c  are used.** to l
322e0 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20  oop through the 
322f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20  virtual table.  
32300 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61  Cursors are crea
32310 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ted using the.**
32320 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65   [sqlite3_module
32330 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20  .xOpen | xOpen] 
32340 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f  method of the mo
32350 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73  dule and are des
32360 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65  troyed.** by the
32370 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65   [sqlite3_module
32380 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65  .xClose | xClose
32390 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f  ] method.  Curso
323a0 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62  rs are used.** b
323b0 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c  y the [xFilter],
323c0 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d   [xNext], [xEof]
323d0 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64  , [xColumn], and
323e0 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64   [xRowid] method
323f0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75  s.** of the modu
32400 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  le.  Each module
32410 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32420 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74  will define.** t
32430 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20  he content of a 
32440 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65  cursor structure
32450 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e   to suit its own
32460 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
32470 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78  is superclass ex
32480 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ists in order to
32490 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f   define fields o
324a0 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61  f the cursor tha
324b0 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20  t.** are common 
324c0 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  to all implement
324d0 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63  ations..*/.struc
324e0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
324f0 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65  ursor {.  sqlite
32500 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20  3_vtab *pVtab;  
32510 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74      /* Virtual t
32520 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72  able of this cur
32530 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  sor */.  /* Virt
32540 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
32550 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
32560 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
32570 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
32580 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
32590 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68  3REF: Declare Th
325a0 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69  e Schema Of A Vi
325b0 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 20 45  rtual Table.** E
325c0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
325d0 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d  * ^The [xCreate]
325e0 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
325f0 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20  methods of a.** 
32600 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
32610 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73  odule] call this
32620 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
32630 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
32640 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
32650 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
32660 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
32670 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
32680 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
32690 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ment..*/.SQLITE_
326a0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
326b0 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
326c0 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
326d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c  const char *zSQL
326e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
326f0 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
32700 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
32710 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 20 45  rtual Table.** E
32720 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
32730 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c  * ^(Virtual tabl
32740 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61  es can provide a
32750 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
32760 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75  mentations of fu
32770 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67  nctions.** using
32780 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74   the [xFindFunct
32790 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ion] method of t
327a0 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
327b0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20  e module].  .** 
327c0 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
327d0 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
327e0 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
327f0 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
32800 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29   be overloaded.)
32810 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41  ^.**.** ^(This A
32820 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
32830 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
32840 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
32850 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
32860 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
32870 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
32880 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
32890 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
328a0 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
328b0 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
328c0 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
328d0 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20   is created.)^  
328e0 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
328f0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
32900 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
32910 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
32920 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
32930 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
32940 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
32950 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
32960 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
32970 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
32980 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
32990 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63  placeholder func
329a0 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65  tion that can be
329b0 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62   overloaded.** b
329c0 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  y a [virtual tab
329d0 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  le]..*/.SQLITE_E
329e0 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
329f0 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
32a00 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
32a10 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
32a20 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
32a30 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
32a40 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
32a50 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
32a60 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
32a70 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
32a80 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
32a90 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
32aa0 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
32ab0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
32ac0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
32ad0 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
32ae0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
32af0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
32b00 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
32b10 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
32b20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
32b30 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
32b40 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
32b50 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
32b60 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
32b70 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
32b80 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
32b90 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
32ba0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
32bb0 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
32bc0 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
32bd0 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
32be0 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
32bf0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
32c00 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
32c10 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
32c20 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
32c30 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
32c40 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
32c50 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20  An Open BLOB.** 
32c60 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20  KEYWORDS: {BLOB 
32c70 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61  handle} {BLOB ha
32c80 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ndles}.**.** An 
32c90 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
32ca0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
32cb0 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
32cc0 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  on which.** [sql
32cd0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
32ce0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
32cf0 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65  B I/O] can be pe
32d00 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a  rformed..** ^Obj
32d10 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
32d20 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
32d30 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
32d40 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65  pen()].** and de
32d50 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
32d60 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
32d70 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  ]..** ^The [sqli
32d80 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
32d90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
32da0 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
32db0 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
32dc0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
32dd0 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
32de0 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
32df0 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  BLOB..** ^The [s
32e00 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
32e10 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  s()] interface r
32e20 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
32e30 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62  of the BLOB in b
32e40 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
32e50 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
32e60 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
32e70 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
32e80 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
32e90 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
32ea0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  I/O.**.** ^(This
32eb0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e   interfaces open
32ec0 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s a [BLOB handle
32ed0 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68   | handle] to th
32ee0 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a  e BLOB located.*
32ef0 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63  * in row iRow, c
32f00 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74  olumn zColumn, t
32f10 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64  able zTable in d
32f20 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20  atabase zDb;.** 
32f30 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
32f40 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68  the same BLOB th
32f50 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
32f60 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
32f70 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
32f80 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
32f90 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
32fa0 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b   [rowid] = iRow;
32fb0 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
32fc0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73  ** ^If the flags
32fd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
32fe0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
32ff0 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
33000 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20  for read.** and 
33010 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49  write access. ^I
33020 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
33030 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
33040 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73   for read access
33050 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20  ..** ^It is not 
33060 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
33070 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
33080 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64  s part of an ind
33090 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a  ex or primary .*
330a0 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e  * key for writin
330b0 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20  g. ^If [foreign 
330c0 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
330d0 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74   are enabled, it
330e0 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73   is .** not poss
330f0 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
33100 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
33110 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b  rt of a [child k
33120 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  ey] for writing.
33130 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
33140 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
33150 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
33160 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
33170 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
33180 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
33190 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
331a0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
331b0 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61  se that.** appea
331c0 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20  rs after the AS 
331d0 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65  keyword when the
331e0 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e   database is con
331f0 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54  nected using [AT
33200 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74  TACH]..** ^For t
33210 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
33220 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62   file, the datab
33230 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69  ase name is "mai
33240 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50  n"..** ^For TEMP
33250 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74   tables, the dat
33260 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74  abase name is "t
33270 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  emp"..**.** ^(On
33280 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
33290 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
332a0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42  d and the new [B
332b0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  LOB handle] is w
332c0 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70  ritten.** to *pp
332d0 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20  Blob. Otherwise 
332e0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
332f0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
33300 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a  *ppBlob is set.*
33310 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70  * to be a null p
33320 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68  ointer.)^.** ^Th
33330 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
33340 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33350 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
33360 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
33370 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
33380 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
33390 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
333a0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
333b0 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75  nd related.** fu
333c0 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74  nctions. ^Note t
333d0 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20  hat the *ppBlob 
333e0 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61  variable is alwa
333f0 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69  ys initialized i
33400 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20  n a.** way that 
33410 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f  makes it safe to
33420 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
33430 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f  _blob_close()] o
33440 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67  n *ppBlob.** reg
33450 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
33460 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
33470 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
33480 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  e..**.** ^(If th
33490 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f  e row that a BLO
334a0 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20  B handle points 
334b0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62  to is modified b
334c0 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  y an.** [UPDATE]
334d0 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62  , [DELETE], or b
334e0 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20  y [ON CONFLICT] 
334f0 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20  side-effects.** 
33500 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61  then the BLOB ha
33510 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61  ndle is marked a
33520 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20  s "expired"..** 
33530 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20  This is true if 
33540 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  any column of th
33550 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64  e row is changed
33560 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a  , even a column.
33570 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68  ** other than th
33580 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68  e one the BLOB h
33590 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e  andle is open on
335a0 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .)^.** ^Calls to
335b0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
335c0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
335d0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
335e0 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72  ] for.** a expir
335f0 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66  ed BLOB handle f
33600 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75  ail with an retu
33610 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
33620 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28  TE_ABORT]..** ^(
33630 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20  Changes written 
33640 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f  into a BLOB prio
33650 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78  r to the BLOB ex
33660 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a  piring are not.*
33670 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  * rolled back by
33680 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20   the expiration 
33690 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75  of the BLOB.  Su
336a0 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ch changes will 
336b0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f  eventually.** co
336c0 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e  mmit if the tran
336d0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65  saction continue
336e0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  s to completion.
336f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68  )^.**.** ^Use th
33700 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
33710 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
33720 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ce to determine 
33730 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74  the size of.** t
33740 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20  he opened blob. 
33750 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20   ^The size of a 
33760 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
33770 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
33780 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
33790 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
337a0 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
337b0 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
337c0 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
337d0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
337e0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
337f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
33800 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
33810 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
33820 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
33830 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
33840 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
33850 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
33860 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
33870 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
33880 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
33890 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
338a0 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
338b0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
338c0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
338d0 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
338e0 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
338f0 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
33900 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
33910 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
33920 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
33930 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69  b_close()]..*/.i
33940 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
33950 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
33960 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
33970 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
33980 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
33990 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
339a0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
339b0 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
339c0 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
339d0 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
339e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
339f0 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
33a00 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  ndle.**.** ^Clos
33a10 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
33a20 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
33a30 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20  ^Closing a BLOB 
33a40 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
33a50 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
33a60 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
33a70 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
33a80 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
33a90 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
33aa0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
33ab0 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
33ac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
33ad0 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
33ae0 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79  ode]..** ^If any
33af0 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
33b00 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
33b10 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
33b20 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
33b30 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
33b40 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
33b50 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
33b60 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  ^(Closing the BL
33b70 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
33b80 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
33b90 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
33ba0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
33bb0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
33bc0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
33bd0 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
33be0 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
33bf0 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65  s closed.  Any e
33c00 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
33c10 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
33c20 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
33c30 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
33c40 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a  turn value.)^.**
33c50 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69  .** ^(The BLOB i
33c60 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
33c70 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
33c80 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
33c90 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
33ca0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
33cb0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
33cc0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  ed.)^.**.** ^Cal
33cd0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
33ce0 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f  e with a null po
33cf0 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77  inter (such as w
33d00 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
33d10 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20  .** by a failed 
33d20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33d30 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
33d40 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
33d50 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
33d60 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
33d70 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
33d80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33d90 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
33da0 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  Of An Open BLOB.
33db0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74  **.** ^Returns t
33dc0 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
33dd0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
33de0 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
33df0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
33e00 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61   opened [BLOB ha
33e10 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
33e20 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  y argument.  ^Th
33e30 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
33e40 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
33e50 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
33e60 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
33e70 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
33e80 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
33e90 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
33ea0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
33eb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33ec0 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
33ed0 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
33ee0 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
33ef0 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
33f00 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
33f10 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
33f20 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
33f30 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
33f40 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
33f50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
33f60 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
33f70 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
33f80 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
33f90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
33fa0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33fb0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33fc0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33fd0 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ior..*/.int sqli
33fe0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
33ff0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
34000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34010 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
34020 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
34030 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ally.**.** ^(Thi
34040 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
34050 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
34060 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
34070 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
34080 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
34090 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
340a0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
340b0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
340c0 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
340d0 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
340e0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
340f0 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a  iOffset.)^.**.**
34100 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
34110 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
34120 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
34130 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
34140 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
34150 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
34160 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
34170 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20  read.  ^If N or 
34180 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
34190 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
341a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
341b0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
341c0 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
341d0 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68   ^The size of th
341e0 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
341f0 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
34200 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
34210 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
34220 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
34230 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
34240 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
34250 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74  e..**.** ^An att
34260 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
34270 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
34280 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
34290 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
342a0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
342b0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
342c0 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
342d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
342e0 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
342f0 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
34300 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
34310 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
34320 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
34330 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
34340 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34350 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
34360 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
34370 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
34380 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
34390 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
343a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
343b0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
343c0 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
343d0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
343e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
343f0 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
34400 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
34410 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
34420 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
34430 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
34440 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
34450 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
34460 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34470 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
34480 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  write()]..*/.int
34490 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
344a0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
344b0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
344c0 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
344d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
344e0 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
344f0 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
34500 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntally.**.** ^Th
34510 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
34520 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
34530 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
34540 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
34550 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
34560 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e  pplied buffer. ^
34570 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
34580 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
34590 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
345a0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
345b0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
345c0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
345d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42  **.** ^If the [B
345e0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
345f0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
34600 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
34610 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
34620 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
34630 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
34640 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
34650 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
34660 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
34670 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
34680 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
34690 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
346a0 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
346b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
346c0 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73   the BLOB; it is
346d0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
346e0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
346f0 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20   size of a BLOB 
34700 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a  using this API..
34710 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
34720 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
34730 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
34740 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
34750 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
34760 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
34770 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
34780 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20  s written.  ^If 
34790 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
347a0 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
347b0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
347c0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
347d0 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
347e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
347f0 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
34800 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
34810 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
34820 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
34830 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
34840 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
34850 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
34860 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
34870 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
34880 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
34890 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
348a0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
348b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
348c0 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20  T].  ^Writes to 
348d0 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63  the BLOB that oc
348e0 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65  curred.** before
348f0 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
34900 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e  e] expired are n
34910 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ot rolled back b
34920 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74  y the.** expirat
34930 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c  ion of the handl
34940 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  e, though of cou
34950 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65  rse those change
34960 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20  s might.** have 
34970 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e  been overwritten
34980 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
34990 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74  t that expired t
349a0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a  he BLOB handle.*
349b0 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e  * or by other in
349c0 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d  dependent statem
349d0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ents..**.** ^(On
349e0 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
349f0 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72  3_blob_write() r
34a00 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
34a10 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
34a20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  an  [error code]
34a30 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
34a40 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
34a50 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
34a60 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
34a70 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
34a80 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
34a90 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
34aa0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
34ab0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
34ac0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34ad0 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
34ae0 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
34af0 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
34b00 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34b10 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
34b20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
34b30 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
34b40 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
34b50 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34b60 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
34b70 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
34b80 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
34b90 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
34ba0 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ad()]..*/.int sq
34bb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
34bc0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
34bd0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
34be0 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
34bf0 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
34c00 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
34c10 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
34c20 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
34c30 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
34c40 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
34c50 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
34c60 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
34c70 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
34c80 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
34c90 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
34ca0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c  ystem.  Most SQL
34cb0 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ite builds come 
34cc0 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
34cd0 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
34ce0 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
34cf0 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
34d00 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
34d10 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
34d20 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
34d30 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
34d40 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
34d50 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
34d60 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
34d70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rovided..**.** ^
34d80 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
34d90 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
34da0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34db0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
34dc0 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  n its name..** ^
34dd0 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
34de0 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61  ensitive..** ^Na
34df0 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
34e00 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
34e10 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  rings..** ^If th
34e20 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
34e30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34e40 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
34e50 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20  ^If zVfsName is 
34e60 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
34e70 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74  fault VFS is ret
34e80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65  urned..**.** ^Ne
34e90 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
34ea0 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
34eb0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
34ec0 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77  ()..** ^Each new
34ed0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
34ee0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
34ef0 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
34f00 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  g is set..** ^Th
34f10 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
34f20 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
34f30 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
34f40 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e  out injury..** ^
34f50 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
34f60 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
34f70 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
34f80 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
34f90 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
34fa0 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
34fb0 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
34fc0 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
34fd0 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
34fe0 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
34ff0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
35000 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
35010 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
35020 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
35030 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
35040 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
35050 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
35060 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
35070 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69  d..**.** ^Unregi
35080 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20  ster a VFS with 
35090 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  the sqlite3_vfs_
350a0 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74  unregister() int
350b0 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20  erface..** ^(If 
350c0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
350d0 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c  is unregistered,
350e0 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20   another VFS is 
350f0 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65  chosen as.** the
35100 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63   default.  The c
35110 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65  hoice for the ne
35120 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61  w VFS is arbitra
35130 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ry.)^.*/.sqlite3
35140 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
35150 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
35160 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
35170 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
35180 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
35190 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
351a0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
351b0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
351c0 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
351d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
351e0 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  utexes.**.** The
351f0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
35200 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
35210 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73   for thread.** s
35220 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20  ynchronization. 
35230 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
35240 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
35250 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
35260 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
35270 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
35280 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
35290 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
352a0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
352b0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
352c0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
352d0 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
352e0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
352f0 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  ons.** of these 
35300 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20  mutex routines. 
35310 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   An appropriate 
35320 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
35330 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75  * is selected au
35340 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63  tomatically at c
35350 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28  ompile-time.  ^(
35360 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
35370 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35380 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
35390 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
353a0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
353b0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
353c0 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
353d0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
353e0 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
353f0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
35400 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
35410 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
35420 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
35430 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
35440 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
35450 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
35460 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68  f routines.** th
35470 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
35480 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
35490 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
354a0 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c  se in.** a singl
354b0 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
354c0 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51  cation.  ^The SQ
354d0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a  LITE_MUTEX_OS2,.
354e0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
354f0 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c  PTHREAD, and SQL
35500 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d  ITE_MUTEX_W32 im
35510 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
35520 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65   are appropriate
35530 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32   for use on OS/2
35540 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64  , Unix, and Wind
35550 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ows..**.** ^(If 
35560 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
35570 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
35580 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
35590 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
355a0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
355b0 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
355c0 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
355d0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
355e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
355f0 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
35600 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
35610 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
35620 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
35630 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
35640 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
35650 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
35660 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
35670 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
35680 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
35690 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
356a0 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
356b0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
356c0 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
356d0 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
356e0 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
356f0 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
35700 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
35710 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
35720 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
35730 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
35740 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
35750 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
35760 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35770 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75   it. ^If it retu
35780 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
35790 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
357a0 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
357b0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51   allocated.  ^SQ
357c0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
357d0 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
357e0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
357f0 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  r.  ^(The argume
35800 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
35810 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
35820 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
35830 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
35840 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35850 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
35860 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
35870 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
35880 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
35890 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
358a0 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
358b0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
358c0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
358d0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
358e0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
358f0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35900 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
35910 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
35920 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
35930 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  U.** <li>  SQLIT
35940 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
35950 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  RU2.** </ul>)^.*
35960 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
35970 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53  two constants (S
35980 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
35990 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
359a0 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20  X_RECURSIVE).** 
359b0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
359c0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
359d0 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
359e0 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20  utex.  ^The new 
359f0 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
35a00 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
35a10 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
35a20 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
35a30 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
35a40 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
35a50 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
35a60 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
35a70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
35a80 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
35a90 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
35aa0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
35ab0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
35ac0 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
35ad0 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
35ae0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
35af0 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  to.  ^SQLite wil
35b00 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
35b10 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
35b20 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
35b30 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
35b40 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66  ds one.  ^If a f
35b50 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
35b60 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
35b70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
35b80 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
35b90 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
35ba0 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
35bb0 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
35bc0 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
35bd0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
35be0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
35bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68  ..**.** ^The oth
35c00 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d  er allowed param
35c10 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  eters to sqlite3
35c20 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28  _mutex_alloc() (
35c30 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a  anything other.*
35c40 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55  * than SQLITE_MU
35c50 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
35c60 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
35c70 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e  IVE) each return
35c80 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
35c90 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
35ca0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53  sting mutex.  ^S
35cb0 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ix static mutexe
35cc0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
35cd0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
35ce0 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
35cf0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
35d00 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
35d10 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
35d20 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
35d30 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
35d40 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
35d50 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
35d60 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
35d70 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
35d80 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
35d90 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
35da0 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
35db0 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
35dc0 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
35dd0 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
35de0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35df0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
35e00 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
35e10 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
35e20 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
35e30 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
35e40 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
35e50 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
35e60 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
35e70 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
35e80 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
35e90 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
35ea0 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20  ery call.  ^But 
35eb0 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a  for the static.*
35ec0 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
35ed0 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
35ee0 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
35ef0 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
35f00 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
35f10 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  e number..**.** 
35f20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
35f30 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
35f40 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
35f50 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
35f60 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
35f70 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20  mutex.  ^SQLite 
35f80 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
35f90 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
35fa0 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
35fb0 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
35fc0 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
35fd0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
35fe0 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68   be in.** use wh
35ff0 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
36000 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
36010 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
36020 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
36030 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
36040 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
36050 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76  or.  ^SQLite nev
36060 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
36070 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
36080 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36090 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
360a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
360b0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
360c0 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
360d0 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
360e0 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68    ^If another th
360f0 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
36100 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
36110 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
36120 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
36130 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
36140 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
36150 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
36160 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20  ITE_BUSY.  ^The 
36170 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36180 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
36190 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
361a0 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
361b0 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d  sful entry.  ^(M
361c0 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
361d0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  sing.** SQLITE_M
361e0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
361f0 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  an be entered mu
36200 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
36210 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
36220 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65  .** In such case
36230 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
36240 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
36250 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
36260 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
36270 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
36280 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e   can enter.)^  ^
36290 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72  (If the same thr
362a0 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74  ead tries to ent
362b0 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  er any other.** 
362c0 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f  kind of mutex mo
362d0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68  re than once, th
362e0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
362f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69  defined..** SQLi
36300 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
36310 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
36320 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
36330 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
36340 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65  .)^.**.** ^(Some
36350 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
36360 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
36370 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
36380 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
36390 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
363a0 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
363b0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
363c0 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
363d0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
363e0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
363f0 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
36400 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
36410 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73  e only ever uses
36420 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
36430 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70  x_try() as an op
36440 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68  timization so th
36450 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
36460 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a   behavior.)^.**.
36470 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36480 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
36490 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
364a0 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
364b0 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
364c0 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
364d0 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62  hread.   ^(The b
364e0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
364f0 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
36500 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
36510 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
36520 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
36530 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
36540 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
36550 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69  ated.  SQLite wi
36560 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
36570 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ither.)^.**.** ^
36580 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
36590 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
365a0 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65  _enter(), sqlite
365b0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f  3_mutex_try(), o
365c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  r.** sqlite3_mut
365d0 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20  ex_leave() is a 
365e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
365f0 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75  en all three rou
36600 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20  tines.** behave 
36610 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  as no-ops..**.**
36620 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36630 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
36640 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
36650 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
36660 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
36670 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
36680 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
36690 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
366a0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
366b0 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
366c0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
366d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
366e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
366f0 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
36700 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
36710 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
36720 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36740 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20  : Mutex Methods 
36750 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49  Object.** EXPERI
36760 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
36770 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
36780 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e   structure defin
36790 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c  es the low-level
367a0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
367b0 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e  d to allocate an
367c0 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a  d use mutexes..*
367d0 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68  *.** Usually, th
367e0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
367f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36800 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69  provided by SQLi
36810 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63  te are.** suffic
36820 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68  ient, however th
36830 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f  e user has the o
36840 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74  ption of substit
36850 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a  uting a custom.*
36860 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
36870 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64   for specialized
36880 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20   deployments or 
36890 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63  systems for whic
368a0 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73  h SQLite.** does
368b0 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73   not provide a s
368c0 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
368d0 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20  tation. In this 
368e0 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a  case, the user.*
368f0 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  * creates and po
36900 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61  pulates an insta
36910 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
36920 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a  cture to pass.**
36930 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
36940 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20  ig() along with 
36950 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
36960 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
36970 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ..** Additionall
36980 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  y, an instance o
36990 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
369a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
369b0 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72  an.** output var
369c0 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79  iable when query
369d0 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66  ing the system f
369e0 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
369f0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
36a00 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68  tation, using th
36a10 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
36a20 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f  _GETMUTEX] optio
36a30 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  n..**.** ^The xM
36a40 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  utexInit method 
36a50 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
36a60 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
36a70 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
36a80 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61  of system initia
36a90 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20  lization by the 
36aa0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
36ab0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ze() function..*
36ac0 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69  * ^The xMutexIni
36ad0 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  t routine is cal
36ae0 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61  le by SQLite exa
36af0 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
36b00 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20  ch.** effective 
36b10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36b20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a  _initialize()]..
36b30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  **.** ^The xMute
36b40 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69  xEnd method defi
36b50 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
36b60 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
36b70 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
36b80 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62  ystem shutdown b
36b90 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68  y the sqlite3_sh
36ba0 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f  utdown() functio
36bb0 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  n. The.** implem
36bc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73  entation of this
36bd0 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63   method is expec
36be0 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61  ted to release a
36bf0 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a  ll outstanding.*
36c00 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61  * resources obta
36c10 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65  ined by the mute
36c20 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d  x methods implem
36c30 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69  entation, especi
36c40 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62  ally.** those ob
36c50 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d  tained by the xM
36c60 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e  utexInit method.
36c70 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64    ^The xMutexEnd
36c80 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
36c90 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  is invoked exact
36ca0 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
36cb0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36cc0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
36cd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69  *.** ^(The remai
36ce0 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f  ning seven metho
36cf0 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  ds defined by th
36d00 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d  is structure (xM
36d10 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d  utexAlloc,.** xM
36d20 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78  utexFree, xMutex
36d30 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79  Enter, xMutexTry
36d40 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78  , xMutexLeave, x
36d50 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a  MutexHeld and.**
36d60 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20   xMutexNotheld) 
36d70 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f  implement the fo
36d80 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
36d90 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79  es (respectively
36da0 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ):.**.** <ul>.**
36db0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
36dc0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
36dd0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
36de0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
36df0 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _free()] </li>.*
36e00 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36e10 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
36e20 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
36e30 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
36e40 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  x_try()] </li>.*
36e50 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36e60 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
36e70 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
36e80 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
36e90 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  x_held()] </li>.
36ea0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
36eb0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
36ec0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  d()] </li>.** </
36ed0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
36ee0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
36ef0 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c  is that the publ
36f00 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66  ic sqlite3_XXX f
36f10 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  unctions enumera
36f20 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c  ted.** above sil
36f30 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79  ently ignore any
36f40 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61   invocations tha
36f50 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f  t pass a NULL po
36f60 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
36f70 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
36f80 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d  x handle. The im
36f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
36fa0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66   the methods def
36fb0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  ined.** by this 
36fc0 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f  structure are no
36fd0 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61  t required to ha
36fe0 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20  ndle this case, 
36ff0 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f  the results.** o
37000 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c  f passing a NULL
37010 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
37020 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
37030 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64  x handle are und
37040 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20  efined.** (i.e. 
37050 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
37060 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69   to provide an i
37070 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
37080 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a  at segfaults if.
37090 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20  ** it is passed 
370a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e  a NULL pointer).
370b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
370c0 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d  xInit() method m
370d0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
370e0 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20  e.  ^It must be 
370f0 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69  harmless to.** i
37100 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74  nvoke xMutexInit
37110 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73  () mutiple times
37120 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
37130 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74   process and wit
37140 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e  hout.** interven
37150 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75  ing calls to xMu
37160 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e  texEnd().  Secon
37170 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
37180 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75   calls to.** xMu
37190 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62  texInit() must b
371a0 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  e no-ops..**.** 
371b0 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75  ^xMutexInit() mu
371c0 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
371d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
371e0 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61  ion ([sqlite3_ma
371f0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69  lloc()].** and i
37200 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20  ts associates). 
37210 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75   ^Similarly, xMu
37220 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
37230 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
37240 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37250 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
37260 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65   mutex.  ^Howeve
37270 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  r xMutexAlloc() 
37280 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a  may use SQLite.*
37290 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
372a0 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f  ion for a fast o
372b0 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  r recursive mute
372c0 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  x..**.** ^SQLite
372d0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
372e0 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74   xMutexEnd() met
372f0 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  hod when [sqlite
37300 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73  3_shutdown()] is
37310 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20  .** called, but 
37320 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f  only if the prio
37330 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78  r call to xMutex
37340 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51  Init returned SQ
37350 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78  LITE_OK..** If x
37360 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20  MutexInit fails 
37370 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69  in any way, it i
37380 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c  s expected to cl
37390 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73  ean up after its
373a0 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  elf.** prior to 
373b0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79  returning..*/.ty
373c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
373d0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
373e0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
373f0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
37400 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37410 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
37420 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
37430 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
37440 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
37450 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
37460 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
37470 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
37480 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
37490 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
374a0 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
374b0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
374c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
374d0 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
374e0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
374f0 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
37500 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
37510 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
37520 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
37530 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
37540 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
37550 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
37560 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37570 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
37580 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
37590 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
375a0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
375b0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
375c0 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
375d0 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
375e0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
375f0 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
37600 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c  ments.  ^The SQL
37610 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
37620 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
37630 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
37640 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
37650 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
37660 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
37670 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
37680 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
37690 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72   ^The SQLite cor
376a0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
376b0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
376c0 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
376d0 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
376e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
376f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
37700 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72  UG flag.  ^Exter
37710 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
37720 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
37730 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
37740 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
37750 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
37760 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
37770 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
37780 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
37790 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
377a0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
377b0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
377c0 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
377d0 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
377e0 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
377f0 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
37800 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
37810 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
37820 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
37830 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
37840 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
37850 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
37860 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
37870 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
37880 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  . If the impleme
37890 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
378a0 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
378b0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
378c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
378d0 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
378e0 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
378f0 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20   that always.** 
37900 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
37910 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
37920 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73   get spurious as
37930 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
37940 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37950 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
37960 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
37970 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
37980 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
37990 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
379a0 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73  turn 1.   This s
379b0 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
379c0 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
379d0 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65  clearly the mute
379e0 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64  x cannot be held
379f0 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
37a00 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a  exist.  But the.
37a10 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68  ** the reason th
37a20 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74  e mutex does not
37a30 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73   exist is becaus
37a40 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e  e the build is n
37a50 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65  ot.** using mute
37a60 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20  xes.  And we do 
37a70 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73  not want the ass
37a80 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67  ert() containing
37a90 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20   the.** call to 
37aa0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
37ab0 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f  ld() to fail, so
37ac0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
37ad0 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70  rn is.** the app
37ae0 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74  ropriate thing t
37af0 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  o do.  ^The sqli
37b00 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
37b10 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
37b20 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
37b30 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
37b40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37b50 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42  .*/.#ifndef NDEB
37b60 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  UG.int sqlite3_m
37b70 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
37b80 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
37b90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
37ba0 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
37bb0 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  ex*);.#endif../*
37bc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
37bd0 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20  tex Types.**.** 
37be0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  The [sqlite3_mut
37bf0 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65  ex_alloc()] inte
37c00 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69  rface takes a si
37c10 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
37c20 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66   which is one of
37c30 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
37c40 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
37c50 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69  The set of stati
37c60 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68  c mutexes may ch
37c70 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51  ange from one SQ
37c80 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20  Lite release to 
37c90 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
37ca0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
37cb0 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69  override the bui
37cc0 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69  lt-in mutex logi
37cd0 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65  c must be.** pre
37ce0 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f  pared to accommo
37cf0 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  date additional 
37d00 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a  static mutexes..
37d10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37d20 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20  E_MUTEX_FAST    
37d30 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
37d40 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37d50 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
37d60 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
37d70 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
37d80 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69  ASTER    2.#defi
37d90 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37da0 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20  STATIC_MEM      
37db0 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   3  /* sqlite3_m
37dc0 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69  alloc() */.#defi
37dd0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37de0 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20  STATIC_MEM2     
37df0 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20   4  /* NOT USED 
37e00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37e10 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f  E_MUTEX_STATIC_O
37e20 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73  PEN      4  /* s
37e30 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28  qlite3BtreeOpen(
37e40 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37e50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37e60 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
37e70 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
37e80 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37e90 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37ea0 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
37eb0 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
37ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37ed0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
37ee0 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72  U2      7  /* lr
37ef0 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a  u page list */..
37f00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37f10 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74  Retrieve the mut
37f20 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ex for a databas
37f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e connection.**.
37f40 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
37f50 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37f60 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65  nter the [sqlite
37f70 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20  3_mutex] object 
37f80 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69  that .** seriali
37f90 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68  zes access to th
37fa0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37fb0 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e  ection] given in
37fc0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
37fd0 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61   when the [threa
37fe0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65  ding mode] is Se
37ff0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49 66  rialized..** ^If
38000 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
38010 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d  mode] is Single-
38020 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d  thread or Multi-
38030 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73  thread then this
38040 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
38050 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
38060 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  er..*/.sqlite3_m
38070 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62  utex *sqlite3_db
38080 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29  _mutex(sqlite3*)
38090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
380a0 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e  F: Low-Level Con
380b0 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65  trol Of Database
380c0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Files.**.** ^Th
380d0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
380e0 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
380f0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72  face makes a dir
38100 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ect call to the.
38110 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
38120 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b  method for the [
38130 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
38140 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  ds] object assoc
38150 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  iated.** with a 
38160 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
38170 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  ase identified b
38180 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
38190 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20 6e  ument. ^The.** n
381a0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
381b0 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20 74  ase "main" for t
381c0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
381d0 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20 74   or "temp" for t
381e0 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61 62  he.** TEMP datab
381f0 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d 65  ase, or the name
38200 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 66   that appears af
38210 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
38220 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  rd for.** databa
38230 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64 64  ses that are add
38240 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41 54  ed using the [AT
38250 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  TACH] SQL comman
38260 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70 6f  d..** ^A NULL po
38270 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73 65  inter can be use
38280 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  d in place of "m
38290 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74 6f  ain" to refer to
382a0 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61 74   the.** main dat
382b0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 5e  abase file..** ^
382c0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
382d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
382e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  to this routine.
382f0 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69  ** are passed di
38300 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74  rectly through t
38310 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  o the second and
38320 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
38330 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c  s of.** the xFil
38340 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
38350 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61    ^The return va
38360 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65  lue of the xFile
38370 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f  Control.** metho
38380 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65  d becomes the re
38390 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
383a0 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
383b0 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
383c0 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e   parameter (zDbN
383d0 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61  ame) does not ma
383e0 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  tch the name of 
383f0 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61  any.** open data
38400 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20  base file, then 
38410 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20  SQLITE_ERROR is 
38420 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69 73  returned.  ^This
38430 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
38440 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64  s not remembered
38450 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
38460 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71   recalled by [sq
38470 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
38480 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
38490 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65 20  errmsg()].  The 
384a0 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65  underlying xFile
384b0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d  Control method m
384c0 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74  ight.** also ret
384d0 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  urn SQLITE_ERROR
384e0 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77  .  There is no w
384f0 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73  ay to distinguis
38500 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20  h between.** an 
38510 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d  incorrect zDbNam
38520 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f  e and an SQLITE_
38530 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f  ERROR return fro
38540 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  m the underlying
38550 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
38560 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53   method..**.** S
38570 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
38580 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
38590 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
385a0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71  _file_control(sq
385b0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
385c0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74  ar *zDbName, int
385d0 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   op, void*);../*
385e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
385f0 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 0a  sting Interface.
38600 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38610 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
38620 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
38630 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20  sed to read out 
38640 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74  internal.** stat
38650 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20  e of SQLite and 
38660 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73  to inject faults
38670 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72   into SQLite for
38680 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70   testing.** purp
38690 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 72 73  oses.  ^The firs
386a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
386b0 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65  n operation code
386c0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
386d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20  .** the number, 
386e0 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65  meaning, and ope
386f0 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75  ration of all su
38700 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
38710 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ers..**.** This 
38720 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
38730 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c   for use by appl
38740 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78  ications.  It ex
38750 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66  ists solely.** f
38760 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65  or verifying the
38770 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69   correct operati
38780 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
38790 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e   library.  Depen
387a0 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74  ding.** on how t
387b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
387c0 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74  y is compiled, t
387d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69  his interface mi
387e0 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a  ght not exist..*
387f0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
38800 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f   of the operatio
38810 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d  n codes, their m
38820 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72  eanings, the par
38830 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20  ameters.** they 
38840 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74  take, and what t
38850 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73  hey do are all s
38860 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
38870 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e   without notice.
38880 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20  .** Unlike most 
38890 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50  of the SQLite AP
388a0 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  I, this function
388b0 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
388c0 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65  ed to.** operate
388d0 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72   consistently fr
388e0 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
388f0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69  o the next..*/.i
38900 6e 74 20 73 7